esbuild-loader-svelte

1.4.0 verified Fri May 01 auth: no javascript

A collection of esbuild plugins for compiling Svelte 5 components (with TypeScript and SCSS support), SCSS styles to CSS, SSR stubbing, raw file imports (?raw suffix), and component meta extraction (?meta suffix). Version 1.4.0. It is actively maintained, ships TypeScript types, and works with esbuild >=0.17.0 and Svelte ^5.0.0. Key differentiators: Svelte 5 Runes support, built-in template engine for SSR, and modular imports.

Common errors

error Cannot find module 'sass' ↓

cause scssPlugin used without installing sass peer dependency.

fix

npm install sass --save-dev

error The requested module 'esbuild-loader-svelte' does not provide an export named 'default' ↓

cause Using default import when only named exports are available.

fix

import { sveltePlugin } from 'esbuild-loader-svelte'

error Error: No matching export in 'esbuild-loader-svelte/raw' for import 'rawPlugin' ↓

cause Typo in subpath or using wrong casing.

fix

Ensure import path is 'esbuild-loader-svelte/raw' (lowercase, no extension).

Warnings

breaking Requires Svelte ^5.0.0; not compatible with Svelte 4 or earlier. ↓

fix Upgrade Svelte to version 5 or use an older version of this package (none exist).

gotcha ESM-only imports from subpaths (e.g., 'esbuild-loader-svelte/svelte') work in Node ESM but may not resolve correctly in CommonJS or bundlers with strict resolver. ↓

fix Use main entry for CJS: const { sveltePlugin } = require('esbuild-loader-svelte');

deprecated The 'filterWarnings' option in sveltePlugin defaults to filtering a11y warnings. ↓

fix If you want to see a11y warnings, pass filterWarnings: () => false.

gotcha scssPlugin requires the 'sass' package to be installed; if missing, esbuild build will throw 'Cannot find module sass'. ↓

fix Install sass: npm install sass --save-dev

Install

npm install esbuild-loader-svelte

yarn add esbuild-loader-svelte

pnpm add esbuild-loader-svelte

Imports

sveltePlugin

wrong

import sveltePlugin from 'esbuild-loader-svelte'

correct

import { sveltePlugin } from 'esbuild-loader-svelte'

Default export does not exist; must use named import.

scssPlugin

wrong

import { scssPlugin } from 'esbuild-loader-svelte'

correct

import { scssPlugin } from 'esbuild-loader-svelte/scss'

Submodule import is available for tree-shaking, but main entry also exports it.

rawPlugin

wrong

const rawPlugin = require('esbuild-loader-svelte/raw')

correct

import { rawPlugin } from 'esbuild-loader-svelte/raw'

CommonJS require works but ESM is preferred when using esbuild.

metaPlugin

wrong

import { metaPlugin } from 'esbuild-loader-svelte/meta.js'

correct

import { metaPlugin } from 'esbuild-loader-svelte/meta'

Do not add .js extension; Node will resolve correctly.

Quickstart

Shows full setup with all core plugins: Svelte compilation, SCSS, raw imports, and meta extraction.

import { sveltePlugin, scssPlugin, rawPlugin, metaPlugin } from 'esbuild-loader-svelte';
import esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    sveltePlugin({ generate: 'client' }),
    scssPlugin(),
    rawPlugin(),
    metaPlugin(),
  ],
});