{"id":22729,"library":"vite-plugin-magic-preloader","title":"vite-plugin-magic-preloader","description":"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.","status":"active","version":"1.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/rzzf/vite-plugin-magic-preloader","tags":["javascript","vite","vite-plugin","preload","prefetch","typescript"],"install":[{"cmd":"npm install vite-plugin-magic-preloader","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-magic-preloader","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-magic-preloader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: >=2.0.0","package":"vite","optional":false}],"imports":[{"note":"ESM-only package; requires dynamic import in CJS or use of Vite's ESM config.","wrong":"const magicPreloader = require('vite-plugin-magic-preloader');","symbol":"default (magicPreloader)","correct":"import magicPreloader from 'vite-plugin-magic-preloader'"},{"note":"Type-only export; import with `type` modifier to avoid runtime errors in bundlers.","wrong":"import { VitePluginMagicPreloaderOptions } from 'vite-plugin-magic-preloader'","symbol":"VitePluginMagicPreloaderOptions","correct":"import type { VitePluginMagicPreloaderOptions } from 'vite-plugin-magic-preloader'"},{"note":"v1.0+ requires calling magicPreloader() as a function; passing the object directly fails.","wrong":"export default defineConfig({ plugins: [magicPreloader] });","symbol":"defineConfig with plugin","correct":"import magicPreloader from 'vite-plugin-magic-preloader';\nexport default defineConfig({ plugins: [magicPreloader()] });"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport vue from '@vitejs/plugin-vue';\nimport magicPreloader from 'vite-plugin-magic-preloader';\n\nexport default defineConfig({\n  plugins: [\n    vue(),\n    magicPreloader(), // Must be after vue plugin for SFC support\n  ],\n});\n\n// In your router/index.ts\nconst routes = [\n  {\n    path: '/lazy',\n    component: () => import(/* vitePrefetch: true */ './LazyComponent.vue'),\n  },\n  {\n    path: '/critical',\n    component: () => import(/* vitePreload: true */ './CriticalComponent.vue'),\n  },\n];","lang":"typescript","description":"Shows basic setup with Vue plugin ordering and usage of magic comments in dynamic imports."},"warnings":[{"fix":"Use dynamic import() syntax with magic comments for lazy-loaded modules.","message":"Only works within import() expressions; static imports are ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Order plugins: [vue(), magicPreloader()].","message":"Plugin must be placed after @vitejs/plugin-vue in the plugins array to process Vue SFC imports.","severity":"gotcha","affected_versions":">=1.0.0 <1.2.0"},{"fix":"Ensure Vue files are processed by vue() before magicPreloader, or extend include to cover .vue if needed (may require additional parser).","message":"Magic 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Override attrs option: magicPreloader({ attrs: { crossorigin: false } })","message":"Cross-origin attribute defaults to true; setting attrs: { crossorigin: false } may be needed for same-origin resources.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change plugins: [magicPreloader] to plugins: [magicPreloader()]","cause":"Passing the plugin object directly instead of calling the exported function.","error":"Error: The plugin 'vite-plugin-magic-preloader' doesn't seem to be a valid Vite plugin."},{"fix":"Install the package: npm install vite-plugin-magic-preloader -D; ensure tsconfig includes 'node_modules/@types'","cause":"Package not installed or TypeScript cannot resolve the module (no typings in some versions).","error":"Cannot find module 'vite-plugin-magic-preloader' or its corresponding type declarations."},{"fix":"Use string, RegExp, or array: magicPreloader({ include: /src\\/.*\\.ts$/ })","cause":"Passing invalid type to include/exclude options (e.g., function or boolean).","error":"[vite] Internal server error: Invalid value for include/exclude. Expected string, RegExp, or array, got object."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}