{"id":13135,"library":"esbuild-vue","title":"esbuild plugin for Vue 2 Single-File Components","description":"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.","status":"maintenance","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/apeschar/esbuild-vue","tags":["javascript"],"install":[{"cmd":"npm install esbuild-vue","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-vue","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-vue","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for compiling Vue 2 single-file components; must match your Vue 2 version.","package":"vue-template-compiler","optional":false}],"imports":[{"note":"The plugin exports a default function. For CommonJS, use direct require. For ESM, use `import vuePlugin from 'esbuild-vue';`","wrong":"const { vuePlugin } = require('esbuild-vue');","symbol":"vuePlugin","correct":"const vuePlugin = require('esbuild-vue');"},{"note":"This is the correct ESM import style for the default export.","symbol":"vuePlugin","correct":"import vuePlugin from 'esbuild-vue';"},{"note":"While esbuild does support ESM, the common pattern with `esbuild-vue` examples uses CommonJS `require` for the build script.","wrong":"import esbuild from 'esbuild';","symbol":"esbuild","correct":"const esbuild = require('esbuild');"}],"quickstart":{"code":"/* Component.vue */\n<template>\n    <h1>Hello from Vue 2!</h1>\n</template>\n\n<script>\nexport default {\n    name: 'HelloWorld'\n}\n</script>\n\n<style scoped>\nh1 {\n    color: #42b983;\n}\n</style>\n\n/* main.js */\nimport Component from './Component.vue';\nimport Vue from 'vue';\n\nnew Vue({\n    el: '#app',\n    render: h => h(Component),\n});\n\n/* build.js */\nconst vuePlugin = require('esbuild-vue');\nconst esbuild = require('esbuild');\n\nesbuild.build({\n    entryPoints: ['main.js'],\n    bundle: true,\n    outfile: 'out.js',\n    plugins: [vuePlugin()],\n    define: {\n        \"process.env.NODE_ENV\": JSON.stringify(\"development\")\n    },\n}).catch(() => process.exit(1));\n\nconsole.log('Build complete: out.js created.');\n\n/* index.html */\n<!doctype html>\n<html>\n<head>\n    <title>esbuild-vue Quickstart</title>\n</head>\n<body>\n    <div id=\"app\"></div>\n    <script src=\"out.js\"></script>\n</body>\n</html>\n","lang":"javascript","description":"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."},"warnings":[{"fix":"For Vue 3 projects, use an alternative like `@vue/compiler-sfc` or other dedicated esbuild plugins for Vue 3 SFCs.","message":"`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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Install `vue-template-compiler` alongside `vue`: `npm install vue@2.x vue-template-compiler@2.x`.","message":"The 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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always create a build script (e.g., `build.js`) and use `require('esbuild').build(...)` to configure and run esbuild with the plugin.","message":"This plugin only integrates with esbuild's JavaScript API. It cannot be used directly with esbuild's command-line interface.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass `{ isAsync: true }` to the plugin constructor: `plugins: [vuePlugin({ isAsync: true })]`.","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `define: { \"process.env.NODE_ENV\": JSON.stringify(\"production\") }` to your esbuild options for production builds.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `plugins: [vuePlugin()]` is present in your esbuild build options. Remember to call `vuePlugin()` as it returns the plugin object.","cause":"The `esbuild-vue` plugin was not correctly included or called in the esbuild configuration.","error":"Plugin error: No loader is configured for \".vue\" files"},{"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.","cause":"The peer dependency `vue-template-compiler` is missing from your project's `node_modules`.","error":"Cannot find module 'vue-template-compiler'"},{"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`).","cause":"The installed versions of `vue` and `vue-template-compiler` are incompatible.","error":"Vue packages version mismatch: ... Vue 2.6.x requires vue-template-compiler 2.6.x ..."},{"fix":"Correct the plugin entry in your esbuild config from `plugins: [vuePlugin]` to `plugins: [vuePlugin()]`.","cause":"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.","error":"Error: The plugin \"esbuild-vue\" was rejected: Plugins must return a value"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}