Vite Plugin Lucide Preprocess

1.4.10 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.4.10) that tree-shakes Lucide icons by transforming non-tree-shakable imports like `import { IconName } from '@lucide/svelte'` into explicit path imports like `import IconName from '@lucide/svelte/icons/icon-name'`. Supports Vite 2+, Rollup 1+, and Rolldown. Features an auto-updater to handle renamed or deprecated Lucide icons automatically. Ships TypeScript types. Compared to manual import rewriting, it automates the process and works across any framework (React, Vue, Svelte, etc.) with Vite.

Common errors

error Error: Plugin vite-plugin-lucide-preprocess: no transformation applied for import from '@lucide/svelte' ↓

cause The plugin expects a default export of the function, but trying to call it with named import or missing plugin registration.

fix

Use the default import: import lucidePreprocess from 'vite-plugin-lucide-preprocess' and add it to plugins: [lucidePreprocess()].

error Uncaught TypeError: Cannot read properties of undefined (reading 'transform') ↓

cause The plugin is not installed or not included in vite.config plugins array.

fix

Install the package: npm install -D vite-plugin-lucide-preprocess and add lucidePreprocess() to the plugins list.

error Module not found: Can't resolve '@lucide/svelte/icons/home' ↓

cause The icon path does not exist; either the icon was renamed or the package is not installed.

fix

Run the auto-updater (wait for it) or verify you have the correct icon name from Lucide documentation. Ensure @lucide/svelte is installed.

Warnings

gotcha Plugin must be added before any other preprocessors in the plugins array; otherwise transformations may be applied to already-processed code. ↓

fix Ensure lucidePreprocess() is the first plugin in the array.

gotcha The plugin only handles imports from Lucide packages (e.g., '@lucide/svelte', 'lucide-react'). It does not transform imports from other icon libraries. ↓

fix Only use with Lucide icon packages.

deprecated Icons in Lucide are frequently renamed or deprecated. The auto-updater may take hours to release a fix, potentially breaking builds. ↓

fix Wait for the auto-updater or manually update icon names in your code. Check the Lucide changelog.

gotcha The plugin uses magic-string for source transformation; source maps may be incorrect if other plugins transform the same code. ↓

fix Test source maps in development and production. Reorder plugins if needed.

Install

npm install vite-plugin-lucide-preprocess

yarn add vite-plugin-lucide-preprocess

pnpm add vite-plugin-lucide-preprocess

Imports

lucidePreprocess (default export)

wrong

const lucidePreprocess = require('vite-plugin-lucide-preprocess')

correct

import lucidePreprocess from 'vite-plugin-lucide-preprocess'

ESM-only (the package is type: module). Named exports not exposed.

plugin usage in vite.config
wrong
```
plugins: [new lucidePreprocess()]
```
correct
```
plugins: [lucidePreprocess()]
```
It's a function call, not a constructor.
Options object (importMode)
wrong
```
lucidePreprocess({ importMode: 'commonjs' })
```
correct
```
lucidePreprocess({ importMode: 'cjs' })
```
Only 'esm' or 'cjs' are valid; 'commonjs' is not recognized.

Quickstart

Adds the plugin to Vite config and demonstrates auto tree-shaking of Lucide icons in a Svelte component.

// vite.config.ts
import { defineConfig } from 'vite';
import lucidePreprocess from 'vite-plugin-lucide-preprocess';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [
    lucidePreprocess(), // must be before other plugins
    svelte()
  ]
});

// Then in your Svelte component:
<script>
  import { Home, User } from '@lucide/svelte';
  // Transformed at build time to:
  // import Home from '@lucide/svelte/icons/home';
  // import User from '@lucide/svelte/icons/user';
</script>

<Home />
<User />