esbuild-vue

library1.2.2jsnpmunverified

This plugin enables esbuild to process and bundle Vue 2 Single-File Components (SFCs). It specifically targets Vue 2, leveraging `vue-template-compiler` (a peer dependency) to compile `<template>`, `<script>`, and `<style>` blocks within `.vue` files into a format consumable by esbuild. The plugin offers features like CSS extraction, PostCSS processing, and can utilize Node.js `worker_threads` via `Piscina` for parallel compilation of multiple SFCs, which can enhance build performance for larger projects. The current stable version is 1.2.2, with its last update occurring in late 2022, suggesting a maintenance-oriented release cadence rather than active feature development. Its primary differentiator is its dedicated focus on integrating existing Vue 2 projects with the esbuild ecosystem, providing a lightweight and fast build solution without requiring an upgrade to Vue 3. It bridges the gap for projects still reliant on the Vue 2 framework, maintaining compatibility with its specific compilation requirements and ecosystem tooling, especially for scenarios where migrating to newer Vue versions is not immediately feasible. It's an alternative for projects looking to modernize their build pipeline using esbuild while remaining on Vue 2.

web-framework serialization

npm install esbuild-vue

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-VUE

esbuild-vue

web-frameworkjavascriptv1.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vuePlugin

✓ const vuePlugin = require('esbuild-vue');

✗ const { vuePlugin } = require('esbuild-vue');

The plugin exports a default function. For CommonJS, use direct require. For ESM, use `import vuePlugin from 'esbuild-vue';`

vuePlugin

✓ import vuePlugin from 'esbuild-vue';

This is the correct ESM import style for the default export.

esbuild

✓ const esbuild = require('esbuild');

✗ import esbuild from 'esbuild';

While esbuild does support ESM, the common pattern with `esbuild-vue` examples uses CommonJS `require` for the build script.

Demonstrates how to set up `esbuild-vue` to compile a basic Vue 2 Single-File Component (SFC) into a browser-loadable JavaScript bundle, including the necessary HTML structure and a build script.

/* Component.vue */ <template> <h1>Hello from Vue 2!</h1> </template> <script> export default { name: 'HelloWorld' } </script> <style scoped> h1 { color: #42b983; } </style> /* main.js */ import Component from './Component.vue'; import Vue from 'vue'; new Vue({ el: '#app', render: h => h(Component), }); /* build.js */ const vuePlugin = require('esbuild-vue'); const esbuild = require('esbuild'); esbuild.build({ entryPoints: ['main.js'], bundle: true, outfile: 'out.js', plugins: [vuePlugin()], define: { "process.env.NODE_ENV": JSON.stringify("development") }, }).catch(() => process.exit(1)); console.log('Build complete: out.js created.'); /* index.html */ <!doctype html> <html> <head> <title>esbuild-vue Quickstart</title> </head> <body> <div id="app"></div> <script src="out.js"></script> </body> </html>

Debug

Known issues

breaking`esbuild-vue` is designed exclusively for Vue 2 applications and is incompatible with Vue 3. Projects migrating to Vue 3 will need a different esbuild plugin for SFC compilation.

fix

For Vue 3 projects, use an alternative like `@vue/compiler-sfc` or other dedicated esbuild plugins for Vue 3 SFCs.

affects: >=1.0.0

gotchaThe plugin requires `vue-template-compiler` as a peer dependency, which must be installed explicitly and its version must match your installed `vue` package version (e.g., Vue 2.6.x needs vue-template-compiler 2.6.x).

fix

Install `vue-template-compiler` alongside `vue`: `npm install vue@2.x vue-template-compiler@2.x`.

affects: >=1.0.0

gotchaThis plugin only integrates with esbuild's JavaScript API. It cannot be used directly with esbuild's command-line interface.

fix

Always create a build script (e.g., `build.js`) and use `require('esbuild').build(...)` to configure and run esbuild with the plugin.

affects: >=1.0.0

gotchaBy default, the plugin uses a synchronous compiler for style blocks. If you are using asynchronous PostCSS plugins, you must explicitly set `isAsync: true` in the plugin options.

fix

Pass `{ isAsync: true }` to the plugin constructor: `plugins: [vuePlugin({ isAsync: true })]`.

affects: >=1.0.0

gotchaFor optimal Vue 2 bundle size and to disable development warnings in production, it is crucial to define `process.env.NODE_ENV` within your esbuild configuration.

fix

Add `define: { "process.env.NODE_ENV": JSON.stringify("production") }` to your esbuild options for production builds.

affects: >=1.0.0

Errors

Common errors & fixes

Plugin error: No loader is configured for ".vue" files

The `esbuild-vue` plugin was not correctly included or called in the esbuild configuration.

fix

Ensure `plugins: [vuePlugin()]` is present in your esbuild build options. Remember to call `vuePlugin()` as it returns the plugin object.

Cannot find module 'vue-template-compiler'

The peer dependency `vue-template-compiler` is missing from your project's `node_modules`.

fix

Install `vue-template-compiler` using your package manager: `npm install vue-template-compiler` or `yarn add vue-template-compiler`. Make sure its version matches your `vue` version.

Vue packages version mismatch: ... Vue 2.6.x requires vue-template-compiler 2.6.x ...

The installed versions of `vue` and `vue-template-compiler` are incompatible.

fix

Ensure both `vue` and `vue-template-compiler` are installed with matching major and minor versions (e.g., `vue@2.6.14` and `vue-template-compiler@2.6.14`).

Error: The plugin "esbuild-vue" was rejected: Plugins must return a value

The `vuePlugin` function was passed directly to the `plugins` array without being called, so esbuild received a function reference instead of the actual plugin object.

fix

Correct the plugin entry in your esbuild config from `plugins: [vuePlugin]` to `plugins: [vuePlugin()]`.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

vue-template-compilerrequiredRequired for compiling Vue 2 single-file components; must match your Vue 2 version.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/apeschar/esbuild-vue ↗

packagehttps://www.npmjs.com/package/esbuild-vue ↗