vite-plugin-magic-preloader

1.2.1 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

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

fix

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

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

cause 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'

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

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

fix

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

Warnings

gotcha Only works within import() expressions; static imports are ignored. ↓

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

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

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

gotcha 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. ↓

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

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

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

Install

npm install vite-plugin-magic-preloader

yarn add vite-plugin-magic-preloader

pnpm add vite-plugin-magic-preloader

Imports

default (magicPreloader)

wrong

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

correct

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

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

VitePluginMagicPreloaderOptions

wrong

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

correct

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

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

defineConfig with plugin

wrong

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

correct

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

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

Quickstart

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'),
  },
];