unplugin-element-plus

0.11.2 verified Mon Apr 27 auth: no javascript

An unplugin-based tool for on-demand Element Plus style imports and locale replacement. Current stable version is 0.11.2. Release cadence is irregular with breaking changes in major versions. Key differentiators: supports Vite, Webpack, Vue CLI, Rollup, esbuild, Rspack, and Rolldown via unplugin. Automatically injects the corresponding CSS/SCSS import for each Element Plus component used. Offers options like `useSource` for SCSS vs CSS, `format` for ESM/CJS, `prefix` for custom component prefixes, and `ignoreComponents` to skip certain components. Ships TypeScript types (v0.11.2).

Common errors

error Error: Cannot find module 'unplugin-element-plus/vite' ↓

cause Using CommonJS require() on an ESM-only package (v0.10.0+).

fix

Use dynamic import: const { default: ElementPlus } = await import('unplugin-element-plus/vite') or switch to ESM config.

error TypeError: ElementPlus is not a function ↓

cause Using default import without .default when require() is used (CommonJS) on ESM package.

fix

Add .default: const ElementPlus = require('unplugin-element-plus/webpack').default

error The 'unplugin-element-plus' package is not compatible with Node.js 18.x. Please upgrade to 20.19+ ↓

cause Using v0.11.0+ which requires Node 20.19+.

fix

Upgrade Node.js to 20.19 or later, or downgrade to unplugin-element-plus@0.10.x.

Warnings

breaking Drop node 18, requires Node 20.19+ ↓

fix Upgrade Node.js to 20.19 or newer.

breaking Drop CJS build; package is ESM-only ↓

fix Use ESM imports (import, import()) or configure bundler to handle ESM. For require() in Node.js, use dynamic import: const { default: ElementPlus } = await import('unplugin-element-plus/vite')

breaking Drop Node 14 & 16 support; drop Webpack 4 & Vue CLI 4 support ↓

fix Upgrade Node to 18+ (or 20.19+ for v0.11+), upgrade Webpack to 5+ and Vue CLI to 5+.

deprecated The `defaultLocale` option is deprecated. Locale replacement moved to a different approach. ↓

fix Use Element Plus's built-in locale system or use `unplugin-vue-components` for locale handling.

gotcha Plugin only transforms imports from 'element-plus' (or custom `lib`). Third-party UI libraries that extend Element Plus are not supported unless they mirror the output structure. ↓

fix Set the `lib` option to match the third-party library's name and ensure its package structure mirrors element-plus.

Install

npm install unplugin-element-plus

yarn add unplugin-element-plus

pnpm add unplugin-element-plus

Imports

ElementPlus (plugin factory)
wrong
```
const ElementPlus = require('unplugin-element-plus/vite')
```
correct
```
import ElementPlus from 'unplugin-element-plus/vite'
```
Since v0.10.0, CJS build is dropped; ESM-only. Use dynamic import if CommonJS required.

ElementPlus (Rollup plugin)

wrong

const ElementPlus = require('unplugin-element-plus/rollup')

correct

import ElementPlus from 'unplugin-element-plus/rollup'

ESM-only; destructure default export. Rollup config must be ESM.

ElementPlus (esbuild plugin)
wrong
```
const ElementPlus = require('unplugin-element-plus/esbuild')
```
correct
```
import ElementPlus from 'unplugin-element-plus/esbuild'
```
ESM-only; use dynamic import in CommonJS esbuild config: const { default: ElementPlus } = await import('unplugin-element-plus/esbuild')
ElementPlus (Webpack plugin)
wrong
```
const ElementPlus = require('unplugin-element-plus/webpack')
```
correct
```
const ElementPlus = require('unplugin-element-plus/webpack').default
```
Webpack configs are often CommonJS; requires .default access. Since v0.10.0, package is ESM but Webpack entry still works with .default.

Quickstart

Shows how to configure vite with ElementPlus plugin and demonstrates automatic style injection for ElButton and ElInput.

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ElementPlus from 'unplugin-element-plus/vite'

export default defineConfig({
  plugins: [
    vue(),
    ElementPlus({
      // Options (optional)
      useSource: false, // Use CSS instead of SCSS
      format: 'esm',
      // ignoreComponents: ['ElAutoResizer']
    }),
  ],
})

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import { ElButton, ElInput } from 'element-plus'

// Without the plugin, you'd need to manually import styles:
// import 'element-plus/es/components/button/style/css'
// import 'element-plus/es/components/input/style/css'

// With the plugin, CSS is automatically injected.
createApp(App).mount('#app')