vite-plugin-lazy-import

1.0.7 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.0.7, last updated 2023) that transforms named imports from large libraries (e.g., vxe-pc-ui) into lazy, per-component import statements, automatically splitting both JavaScript and CSS. Designed for on-demand loading in Vite projects, it resolves imports to individual module paths and can inject corresponding style imports. Unlike general tree-shaking, this works at the import level, converting `import { X } from 'lib'` into `import X from 'lib/es/X/index.js'` plus optional CSS. ESM-only, TypeScript types included, maintained by the vxe-pc-ui author. Releases are infrequent; no known security incidents.

Common errors

error TypeError: Cannot destructure property 'lazyImport' of '...' as it is undefined. ↓

cause Using default import instead of named import after version 1.0.4.

fix

Use import { lazyImport } from 'vite-plugin-lazy-import'

error Error: The library 'my-lib' is not configured in lazyImport resolvers. ↓

cause Library not added to resolvers array.

fix

Add an entry for 'my-lib' in the resolvers array of the plugin options.

error Module not found: Error: Can't resolve 'vxe-pc-ui/es/vxe-button/index.js' ↓

cause The resolved path does not exist; likely because `esm: true` is not set or the library structure differs.

fix

Set esm: true if using ESM path, or adjust the resolve function to match the actual library structure.

Warnings

gotcha The plugin only transforms imports from libraries explicitly listed in `resolvers`. Other imports are left untouched. ↓

fix Ensure your target library is added to the resolvers array.

gotcha The `esm` option must be set to `true` to use '/es/' directory paths; otherwise it defaults to '/lib/'. ↓

fix Explicitly set `esm: true` in your resolver config if your library uses ESM structure.

gotcha If `importStyle` is not set, no style imports are added even if `stylePath` is provided in `resolve`. ↓

fix Set `importStyle: true` or `importStyle: 'css'` to enable style injection.

gotcha The plugin does not handle dynamic imports or re-exports; it only rewrites static `import { ... } from 'lib'` statements. ↓

fix Use only static import syntax for the libraries you want to lazy-load.

breaking Version 1.0.4 changed the plugin's API from default export to named export `lazyImport`. Old code using `import vitePluginLazyImport from 'vite-plugin-lazy-import'` will break. ↓

fix Change to `import { lazyImport } from 'vite-plugin-lazy-import'`

Install

npm install vite-plugin-lazy-import

yarn add vite-plugin-lazy-import

pnpm add vite-plugin-lazy-import

Imports

lazyImport

wrong

import lazyImport from 'vite-plugin-lazy-import'

correct

import { lazyImport } from 'vite-plugin-lazy-import'

This is a named export, not default. Must use destructuring.

lazyImport
wrong
```
const lazyImport = require('vite-plugin-lazy-import')
```
correct
```
const { lazyImport } = require('vite-plugin-lazy-import')
```
CommonJS require works, but must destructure the named export. However, Vite config is typically ESM.
ResolveOptions
wrong
```
import { ResolveOptions } from 'vite-plugin-lazy-import'
```
correct
```
import type { ResolveOptions } from 'vite-plugin-lazy-import'
```
ResolveOptions is a TypeScript type, should be imported with `import type` for type-only usage. If used as value, it's a runtime error.

Quickstart

Configures the plugin to rewrite named imports from 'vxe-pc-ui' into per-component ESM imports with CSS.

// vite.config.ts
import { defineConfig } from 'vite'
import { lazyImport } from 'vite-plugin-lazy-import'

export default defineConfig({
  plugins: [
    lazyImport({
      resolvers: [
        {
          lib: 'vxe-pc-ui',
          importStyle: 'css',
          esm: true,
          resolve({ name, dirName }) {
            return {
              from: `vxe-pc-ui/es/${dirName}/index.js`
            }
          }
        }
      ]
    })
  ]
})

// Then in your app:
// import { VxeButton } from 'vxe-pc-ui'
// becomes:
// import { VxeButton } from 'vxe-pc-ui/es/vxe-button/index.js'