esbuild Vue Plugin

0.2.4 · active · verified Sun Apr 19

esbuild-plugin-vue provides basic support for processing Vue 3 Single File Components (SFCs) directly within esbuild build pipelines. It enables core features like `<script setup>` syntax, TypeScript integration within script blocks, and scoped CSS styles, allowing developers to leverage esbuild's speed for compiling Vue applications. As of version 0.2.4, it is considered pre-1.0, indicating ongoing development and potential for API changes without strictly adhering to semantic versioning until a 1.x release. The plugin differentiates itself by offering a lightweight, esbuild-native solution for Vue SFC compilation, aiming for simplicity and performance over the more extensive feature sets of dedicated Vue build tools like Vite or Vue CLI. It utilizes `@vue/compiler-sfc` under the hood to perform the actual Vue compilation. The package appears to be actively maintained, evidenced by recent updates and a call for sponsorship.

Common errors

```
Error: Cannot find module '@vue/compiler-sfc'
```
cause The `@vue/compiler-sfc` package, which `esbuild-plugin-vue` depends on for Vue SFC compilation, is not installed.

fix Install the missing peer dependency: `npm install @vue/compiler-sfc` or `yarn add @vue/compiler-sfc`.
```
Plugin "vue" failed with error: [Error: build-stdio] 'esbuild' peer dependency not found.
```
cause `esbuild` itself, the core bundler, is either not installed or its version does not match the plugin's peer dependency range.

fix Install `esbuild` to a compatible version: `npm install esbuild@"^0.x.y"` (replacing `x.y` with a version within the plugin's specified range `">=0.11 <=1"`).
```
SyntaxError: Named export 'vue' not found. Did you mean to import the default export?
```
cause Attempting to destructure `vue` as a named export when it is exported as the default.

fix Change your import statement from `import { vue } from 'esbuild-plugin-vue'` to `import vue from 'esbuild-plugin-vue'`.

Warnings

breaking As a pre-1.0 package (version 0.2.4), `esbuild-plugin-vue` may introduce breaking changes in minor or patch releases without strict adherence to semantic versioning. Users should review changelogs carefully when upgrading.
Fix: Always test new versions in a development environment before deploying to production. Monitor the package's GitHub repository for pre-release announcements or breaking change notes.
gotcha The plugin has a specific peer dependency range for `esbuild` (`>=0.11 <=1`). Installing a version of `esbuild` outside this range (e.g., a future 0.x release beyond 0.11 but still before 1.0, or a hypothetical esbuild 2.0) might lead to incompatibility issues or runtime errors.
Fix: Ensure your `esbuild` version precisely matches the peer dependency range. Use `npm install esbuild@<version>` or `yarn add esbuild@<version>` to pin to a compatible version if necessary.
gotcha The plugin provides 'basic .vue support' and might not cover all advanced features or edge cases of Vue SFC compilation found in more mature, official build tools like Vite or Vue CLI. Complex setups or highly optimized scenarios might require additional esbuild plugins or manual configuration.
Fix: For complex Vue applications, evaluate if this plugin meets all requirements. Be prepared to implement custom esbuild plugins or fallback to official Vue tooling if advanced features are missing or problematic.

Install

npm install esbuild-plugin-vue npm
yarn add esbuild-plugin-vue yarn
pnpm add esbuild-plugin-vue pnpm

Imports

vue
wrong:
```
import { vue } from 'esbuild-plugin-vue'
```
correct:
```
import vue from 'esbuild-plugin-vue'
```
The plugin factory is the default export. Destructuring it will result in an undefined value.
build
wrong:
```
const { build } = require('esbuild')
```
correct:
```
import { build } from 'esbuild'
```
While esbuild supports CommonJS, modern usage and examples (including for this plugin) primarily use ESM imports.
Plugin
```
import type { Plugin } from 'esbuild'
```
When writing custom esbuild plugins or extending existing ones, import the Plugin type for type safety.

Quickstart

Demonstrates how to integrate `esbuild-plugin-vue` into an esbuild configuration to compile a basic Vue 3 SFC with `<script setup>`, TypeScript, and scoped styles.

import { build } from 'esbuild';
import vue from 'esbuild-plugin-vue';
import path from 'path';
import fs from 'fs';

// Create a dummy Vue SFC for demonstration
const vueComponentContent = `
<template>
  <div>Hello from Vue, {{ message }}!</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
const message = ref('esbuild-plugin-vue');
</script>

<style scoped>
div {
  color: #42b983;
}
</style>
`;
const entryPointPath = path.resolve(__dirname, 'src', 'main.ts');
const vueComponentPath = path.resolve(__dirname, 'src', 'App.vue');

fs.mkdirSync(path.dirname(entryPointPath), { recursive: true });
fs.writeFileSync(vueComponentPath, vueComponentContent);
fs.writeFileSync(entryPointPath, `import App from './App.vue'; console.log(App);`);

(async () => {
  try {
    await build({
      entryPoints: [entryPointPath],
      bundle: true,
      outfile: path.resolve(__dirname, 'dist', 'bundle.js'),
      plugins: [vue()],
      format: 'esm',
      logLevel: 'info'
    });
    console.log('Build successful!');
  } catch (e) {
    console.error('Build failed:', e);
  }
})();

view raw JSON →