Registry / web-framework / vite-plugin-magic-preloader

vite-plugin-magic-preloader

library1.2.1jsnpmunverified

Vite plugin that enables Webpack-style magic comments (/* vitePrefetch: true */, /* vitePreload: true */) for dynamic imports, allowing fine-grained control over preloading and prefetching of resources. Current stable version: 1.2.1. Released: December 2021, with recent updates adding attrs support (functions accepted in v1.1.1). Only works within import() statements; does not affect static imports. Key differentiator: provides magic comments missing from Rollup/Vite, targeting Vue and React lazy-loaded routes. Ships TypeScript types. Requires Vite >= 2.0.0 as peer dependency.

web-framework devops

npm install vite-plugin-magic-preloader

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-MAGIC-

vite-plugin-magic-preloader

web-frameworkjavascriptv1.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (magicPreloader)

✓ import magicPreloader from 'vite-plugin-magic-preloader'

✗ const magicPreloader = require('vite-plugin-magic-preloader');

ESM-only package; requires dynamic import in CJS or use of Vite's ESM config.

VitePluginMagicPreloaderOptions

✓ import type { VitePluginMagicPreloaderOptions } from 'vite-plugin-magic-preloader'

✗ import { VitePluginMagicPreloaderOptions } from 'vite-plugin-magic-preloader'

Type-only export; import with `type` modifier to avoid runtime errors in bundlers.

defineConfig with plugin

✓ import magicPreloader from 'vite-plugin-magic-preloader'; export default defineConfig({ plugins: [magicPreloader()] });

✗ export default defineConfig({ plugins: [magicPreloader] });

v1.0+ requires calling magicPreloader() as a function; passing the object directly fails.

Shows basic setup with Vue plugin ordering and usage of magic comments in dynamic imports.

// vite.config.ts import { defineConfig } from 'vite'; import vue from '@vitejs/plugin-vue'; import magicPreloader from 'vite-plugin-magic-preloader'; export default defineConfig({ plugins: [ vue(), magicPreloader(), // Must be after vue plugin for SFC support ], }); // In your router/index.ts const routes = [ { path: '/lazy', component: () => import(/* vitePrefetch: true */ './LazyComponent.vue'), }, { path: '/critical', component: () => import(/* vitePreload: true */ './CriticalComponent.vue'), }, ];

Debug

Known issues

gotchaOnly works within import() expressions; static imports are ignored.

fix

Use dynamic import() syntax with magic comments for lazy-loaded modules.

affects: >=1.0.0

gotchaPlugin must be placed after @vitejs/plugin-vue in the plugins array to process Vue SFC imports.

fix

Order plugins: [vue(), magicPreloader()].

affects: >=1.0.0 <1.2.0

gotchaMagic comments are only parsed if the file matches include pattern (default: .js/.ts/.jsx/.tsx). Vue SFCs are processed only when used after @vitejs/plugin-vue.

fix

Ensure Vue files are processed by vue() before magicPreloader, or extend include to cover .vue if needed (may require additional parser).

affects: >=1.0.0

gotchaCross-origin attribute defaults to true; setting attrs: { crossorigin: false } may be needed for same-origin resources.

fix

Override attrs option: magicPreloader({ attrs: { crossorigin: false } })

affects: >=1.1.0

Errors

Common errors & fixes

Error: The plugin 'vite-plugin-magic-preloader' doesn't seem to be a valid Vite plugin.

Passing the plugin object directly instead of calling the exported function.

fix

Change plugins: [magicPreloader] to plugins: [magicPreloader()]

Cannot find module 'vite-plugin-magic-preloader' or its corresponding type declarations.

Package not installed or TypeScript cannot resolve the module (no typings in some versions).

fix

Install the package: npm install vite-plugin-magic-preloader -D; ensure tsconfig includes 'node_modules/@types'

[vite] Internal server error: Invalid value for include/exclude. Expected string, RegExp, or array, got object.

Passing invalid type to include/exclude options (e.g., function or boolean).

fix

Use string, RegExp, or array: magicPreloader({ include: /src\/.*\.ts$/ })

Upgrade

Version history

1.2.1latest on npm

Audit

Dependencies

viterequiredpeer dependency: >=2.0.0

Agent activity

14 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

githubhttps://github.com/rzzf/vite-plugin-magic-preloader ↗

packagehttps://www.npmjs.com/package/vite-plugin-magic-preloader ↗