vite-plugin-transform-lucide-imports

0.3.1 verified Mon Apr 27 auth: no javascript

A Vite plugin (v0.3.1) that transforms named imports from lucide icon packages into default imports for improved dev server performance and tree-shaking. It is actively maintained with patches for Vite 8 compatibility and handles aliased icons, type imports, and multiple frameworks (React, Svelte, vanilla JS). Unlike alternatives that require manual refactoring, this plugin automates the conversion with zero config. Supports custom file extensions for other frameworks.

Common errors

error Error: 'default' is not exported by node_modules/vite-plugin-transform-lucide-imports/dist/index.mjs, imported by vite.config.ts ↓

cause Using named import { transformLucideImports } instead of default import.

fix

Change to: import transformLucideImports from 'vite-plugin-transform-lucide-imports';

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

cause Plugin version <0.3.0 does not support the 'onwarn' option.

fix

Update to >=0.3.0 or remove the 'onwarn' option from plugin config.

error Transform failed with error: Cannot read properties of undefined (reading 'includes') ↓

cause Plugin ran before framework plugin transformed the file (e.g., .svelte).

fix

Place transformLucideImports() after the Svelte/Vue plugin in the plugins array.

error WARN: No matching lucide package found for import from 'lucide-react' ↓

cause The lucide-react package already supports tree-shaking and is skipped by default.

fix

This warning is informational; no action needed. The import remains unchanged.

Warnings

gotcha Plugin must be placed AFTER framework plugins (e.g., SvelteKit) in the plugins array to work correctly. ↓

fix Ensure transformLucideImports() is listed after plugins that transpile files like .svelte or .vue.

gotcha The plugin does not optimize lucide packages that already support tree-shaking (lucide, lucide-react, lucide-vue, etc.). It only targets packages like lucide-react-native. ↓

fix Use this plugin only for lucide packages that lack built-in tree-shaking (e.g., lucide-react-native).

breaking In version 0.2.0, the plugin now skips tree-shaken packages to avoid optimization. This may affect projects relying on explicit optimization. ↓

fix No action needed; the plugin automatically handles it.

deprecated The 'onwarn' option added in 0.3.0 is experimental and may change in future versions. ↓

fix Use with caution and review changelog before updating.

gotcha Type-only imports (e.g., import type { XIcon } from ...) are preserved but moved to separate import statements; ensure your config supports type imports. ↓

fix Enable 'verbatimModuleSyntax' in tsconfig.json to keep type imports explicit.

Install

npm install vite-plugin-transform-lucide-imports

yarn add vite-plugin-transform-lucide-imports

pnpm add vite-plugin-transform-lucide-imports

Imports

transformLucideImports

wrong

import { transformLucideImports } from 'vite-plugin-transform-lucide-imports'

correct

import transformLucideImports from 'vite-plugin-transform-lucide-imports'

Default export only; named destructure will cause undefined.

SUPPORTED_EXTENSIONS

wrong

import SUPPORTED_EXTENSIONS from 'vite-plugin-transform-lucide-imports'

correct

import { SUPPORTED_EXTENSIONS } from 'vite-plugin-transform-lucide-imports'

Named export, not default.

VitePluginTransformLucideImports

wrong

import { VitePluginTransformLucideImports } from 'vite-plugin-transform-lucide-imports'

correct

import type { VitePluginTransformLucideImports } from 'vite-plugin-transform-lucide-imports'

TypeScript type only; do not use as value.

Quickstart

Shows minimal Vite config with the plugin, and the transformation effect on import statements.

// Install: npm i -D vite-plugin-transform-lucide-imports
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import transformLucideImports from 'vite-plugin-transform-lucide-imports';

export default defineConfig({
  plugins: [react(), transformLucideImports()],
});

// Before: import { HomeIcon } from 'lucide-react';
// After: import HomeIcon from 'lucide-react/icons/home';