Vite Plugin Dynamic Import

1.6.0 verified Sat Apr 25 auth: no javascript

Enhances Vite's built-in dynamic import support by adding alias resolution (e.g., `@/views/${variable}`), bare module imports from node_modules, and automatic file extension resolution. Current stable version 1.6.0, released regularly with contributions from the community. Differentiators: provides a 'loose' mode similar to Webpack's dynamic import behavior, resolves glob patterns to handle missing extensions and paths, and works around `@rollup/plugin-dynamic-import-vars` limitations. Requires Vite as a peer dependency and is used as a Vite plugin.

Common errors

error Error: Cannot find module 'vite-plugin-dynamic-import' ↓

cause Using require() in a CommonJS context; package is ESM-only.

fix

Use import statement (ESM) or switch to an ESM module (e.g., type: "module" in package.json).

error Dynamic import with alias not resolved: `import('@/views/${variable}')` ↓

cause Alias is not recognized without the plugin; Vite does not resolve aliases in dynamic imports by default.

fix

Install and configure vite-plugin-dynamic-import in vite.config.js.

error The plugin does not transform dynamic imports inside node_modules ↓

cause The default filter excludes node_modules.

fix

Add a filter option that returns true for the specific module paths.

error Module not found: Cannot resolve '...' (dynamic import with missing extension) ↓

cause The dynamic import path does not include the file extension, and Vite cannot guess it.

fix

Ensure that resolve.extensions includes the needed extensions. The plugin helps but may require explicit globbing.

Warnings

breaking The plugin requires Vite 2.x or newer; Vite 1.x is not supported. ↓

fix Upgrade to Vite 2+

gotcha By default, the plugin excludes node_modules. You must explicitly set the `filter` option to include bare module imports from node_modules. ↓

fix Add a filter callback returning true for node_modules paths you want to transform.

deprecated In version 1.5.0, the `onFiles` option was introduced; older versions had a different mechanism for excluding files. ↓

fix Use `onFiles` callback instead of previous undefined behavior.

gotcha When using `loose: true`, the plugin may over-match patterns and generate many switch cases, leading to large bundle sizes. ↓

fix Use `loose: false` for stricter matching similar to @rollup/plugin-dynamic-import-vars.

gotcha The plugin relies on Vite's resolve.alias and resolve.extensions configurations; dynamic imports may not work if these are not properly set. ↓

fix Define aliases in vite.config.js resolve.alias and set resolve.extensions as needed.

Install

npm install vite-plugin-dynamic-import

yarn add vite-plugin-dynamic-import

pnpm add vite-plugin-dynamic-import

Imports

default

wrong

const dynamicImport = require('vite-plugin-dynamic-import')

correct

import dynamicImport from 'vite-plugin-dynamic-import'

ESM-only package; CommonJS require() will fail.

dynamicImport (default import)

wrong

import { dynamicImport } from 'vite-plugin-dynamic-import'

correct

import dynamicImport from 'vite-plugin-dynamic-import'

The package exports a single function as default export, not a named export.

Options type
```
import type { Options } from 'vite-plugin-dynamic-import'
```
TypeScript users can import the Options interface for type checking, but it's not necessary at runtime.

Quickstart

Shows how to configure the plugin in vite.config.js to enable dynamic imports with aliases, node_modules inclusion, file filtering, and custom resolution.

// vite.config.js
import { defineConfig } from 'vite'
import dynamicImport from 'vite-plugin-dynamic-import'

export default defineConfig({
  plugins: [
    dynamicImport({
      loose: true,
      filter(id) {
        // default excludes node_modules; include if needed
        if (id.includes('/node_modules/some-module')) {
          return true
        }
      },
      onFiles(files, id) {
        // exclude certain files like .d.ts
        return files.filter(f => !f.endsWith('.d.ts'))
      },
      onResolve(rawImportee, id) {
        // prepend @vite-ignore to bypass Vite's dynamic import warning
        return `\/*@vite-ignore*\/ ${rawImportee}`
      }
    })
  ]
})

// router.js (example usage)
const route = await import(`./views/${someVariable}.js`) // now supports aliases and missing extensions