esbuild-svelte

0.9.4 verified Mon Apr 27 auth: no javascript

esbuild plugin that resolves and compiles .svelte files for bundling with esbuild. Current stable version 0.9.4, actively maintained. Supports Svelte 4 and 5 (peer dep range >=4.2.1 <6). Key differentiators: zero-config setup for CSS handling (external by default, can inject), built-in caching for incremental builds, and full support for Svelte preprocessors including TypeScript. Compared to alternatives like svelte-loader for webpack or vite-plugin-svelte, this plugin is tailored for esbuild's speed and simplicity, with minimal dependencies and straightforward API.

Common errors

error Error: No matching export in 'esbuild-svelte' for import 'sveltePlugin' ↓

cause Incorrect named import instead of default import.

fix

Change to: import sveltePlugin from 'esbuild-svelte';

error TypeError: sveltePlugin is not a function ↓

cause Using CommonJS require which returns a module object instead of the default export.

fix

Use ESM import or use require('esbuild-svelte').default.

error Cannot find module 'esbuild-svelte' ↓

cause Missing dependency or incorrect Node version (<18).

fix

Run 'npm install esbuild-svelte' and ensure Node >=18.

error Error: The 'svelte' package must be installed and version >=4.2.1 ↓

cause Missing or outdated peer dependency svelte.

fix

Run 'npm install svelte@^4.2.1'.

error Error: '@sveltejs/vite-plugin-svelte' is not compatible with esbuild-svelte ↓

cause Conflicting plugins; both handle .svelte files.

fix

Remove vite-plugin-svelte from plugins array when using esbuild-svelte.

Warnings

breaking Version 0.8.0 dropped support for Svelte 3 and Node <18. ↓

fix Upgrade Svelte to >=4.2.1 and Node to >=18.

deprecated The 'external' option in plugin options has been deprecated; use compilerOptions.css instead. ↓

fix Set compilerOptions.css: 'external' to emit external CSS, or 'injected' to include in JS.

gotcha Missing 'svelte' in esbuild conditions or mainFields causes resolution failures for Svelte component libraries. ↓

fix Add 'svelte' to conditions and 'svelte' to mainFields in esbuild build options.

gotcha Plugin does not handle HMR or dev server; it's a compile-only plugin. ↓

fix Use a separate dev server like sirv and configure esbuild in watch mode, or consider vite-plugin-svelte for dev experience.

breaking In version 0.7.0, the default CSS handling changed from 'injected' to 'external'. ↓

fix Explicitly set compilerOptions.css if default behavior matters.

Install

npm install esbuild-svelte

yarn add esbuild-svelte

pnpm add esbuild-svelte

Imports

default export (sveltePlugin)
wrong
```
const sveltePlugin = require('esbuild-svelte')
```
correct
```
import sveltePlugin from 'esbuild-svelte'
```
ESM-only; CommonJS require will fail. Also, avoid importing from a subpath like 'esbuild-svelte/plugin'.
sveltePlugin
wrong
```
import { sveltePlugin } from 'esbuild-svelte'
```
correct
```
import sveltePlugin from 'esbuild-svelte'
```
The plugin is a default export, not a named export. Named import will be undefined.
SveltePluginOptions (TypeScript type)
wrong
```
import { SveltePluginOptions } from 'esbuild-svelte'
```
correct
```
import type { SveltePluginOptions } from 'esbuild-svelte'
```
Use 'import type' for type-only imports to avoid runtime issues with ESM.

Quickstart

Shows minimal esbuild build script with sveltePlugin, including required mainFields and conditions for Svelte component resolution.

import esbuild from 'esbuild';
import sveltePlugin from 'esbuild-svelte';

await esbuild.build({
  entryPoints: ['src/main.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [sveltePlugin()],
  mainFields: ['svelte', 'browser', 'module', 'main'],
  conditions: ['svelte', 'browser'],
  logLevel: 'info',
});