esbuild-plugin-vue3

0.5.1 verified Mon Apr 27 auth: no javascript

esbuild plugin for Vue.js 3 Single File Components, mimicking Vue CLI behavior. Version 0.5.1 supports .vue file resolution with <template> (HTML/Pug), <script> (JS/TS, including <script setup> as experimental), and <style> (CSS/SCSS/SASS). It resolves path aliases from tsconfig.json and can emit HTML files with injected CSS/JS. Peer dependencies include vue@^3.4.15, cheerio, html-minifier, pug, and sass. Compared to alternatives like @snowpack/plugin-vue or vite's built-in plugin, this targets esbuild-only builds.

Common errors

error Error: Cannot find module 'cheerio' ↓

cause Missing optional peer dependency cheerio when using HTML generation.

fix

Install required peer dependencies: npm i cheerio html-minifier

error TypeError: vuePlugin is not a function ↓

cause Using ES import syntax with CJS package incorrectly.

fix

Use const vuePlugin = require('esbuild-plugin-vue3') instead of import.

error Error: Could not resolve './App.vue' from 'src/main.ts' ↓

cause Path alias not recognized due to missing tsconfig.json or incorrect alias configuration.

fix

Create a tsconfig.json in project root with paths, or pass alias option explicitly.

Warnings

gotcha Plugin is not thoroughly tested; use at your own risk. ↓

fix Consider using more mature alternatives like @vitejs/plugin-vue or vue-loader for production.

breaking Version 0.5.1 changed the way HTML generation works: options.generateHTML now accepts a string or an object. ↓

fix If upgrading from 0.4.x, update the generateHTML option format.

gotcha Path aliases from tsconfig.json are resolved automatically, but only if a tsconfig.json exists in the working directory. ↓

fix Ensure tsconfig.json is present or explicitly set the alias option.

deprecated script setup support is still experimental and may have bugs or missing features. ↓

fix Test thoroughly; consider using <script> with setup() function as fallback.

Install

npm install esbuild-plugin-vue3

yarn add esbuild-plugin-vue3

pnpm add esbuild-plugin-vue3

Imports

default (plugin function)
wrong
```
const vuePlugin = require('esbuild-plugin-vue3').default
```
correct
```
import vuePlugin from 'esbuild-plugin-vue3'
```
The package is CJS; default export is obtained via require('esbuild-plugin-vue3').
default (plugin function) via require
```
const vuePlugin = require('esbuild-plugin-vue3')
```
CJS require yields the default export directly.
TypeScript (type imports not provided)
```
// No type exports; use // @ts-ignore if needed
```
Package does not export type definitions; use any or declare module.

Quickstart

Minimal esbuild setup using esbuild-plugin-vue3 to bundle a Vue 3 SFC entry point into a single JS file.

const esbuild = require('esbuild');
const vuePlugin = require('esbuild-plugin-vue3');

async function build() {
  await esbuild.build({
    entryPoints: ['src/app.ts'],
    bundle: true,
    outfile: 'dist/app.js',
    plugins: [vuePlugin()],
  });
}

build().catch(console.error);