esbuild-loader-svelte

A collection of esbuild plugins for compiling Svelte 5 components, SCSS styles, SSR stub replacement, raw source imports and meta extraction.

Features

• Compile .svelte files with TypeScript and SCSS preprocessing
• Compile .scss files to CSS
• Replace browser-only modules with stubs in SSR builds
• Import files as raw text (?raw suffix)
• Extract Svelte component metadata (?meta suffix)
• Template engine for reading and rendering placeholder templates
• Compatible with CommonJS and ES Modules
• Svelte 5 Runes mode supported

Installation

npm Install

# npm
npm install esbuild-loader-svelte --save-dev

# cnpm（国内镜像）
cnpm install esbuild-loader-svelte --save-dev

# yarn
yarn add esbuild-loader-svelte --dev

# pnpm
pnpm add esbuild-loader-svelte -D

Peer Dependencies

Make sure the following dependencies are installed:

npm install esbuild svelte --save-dev

# SCSS 支持（可选）
npm install sass --save-dev

ES Module Import

// 导入全部插件
import { sveltePlugin, scssPlugin, ssrStubPlugin, rawPlugin, metaPlugin } from 'esbuild-loader-svelte'

// 按需导入单个插件
import { sveltePlugin } from 'esbuild-loader-svelte/svelte'
import { scssPlugin } from 'esbuild-loader-svelte/scss'
import { ssrStubPlugin } from 'esbuild-loader-svelte/ssr-stub'
import { rawPlugin } from 'esbuild-loader-svelte/raw'
import { metaPlugin } from 'esbuild-loader-svelte/meta'
import { obfuscatorPlugin } from 'esbuild-loader-svelte/obfuscator'

CommonJS Require

const { sveltePlugin, scssPlugin } = require('esbuild-loader-svelte')

Quick Start

// build.js
import esbuild from 'esbuild'
import { sveltePlugin, scssPlugin } from 'esbuild-loader-svelte'

await esbuild.build({
  entryPoints: ['src/main.js'],
  bundle: true,
  outdir: 'dist',
  plugins: [sveltePlugin(), scssPlugin()],
})

Plugin List

sveltePlugin

Compile .svelte files to JavaScript with TypeScript and SCSS preprocessing.

Param

Example

import esbuild from 'esbuild'
import { sveltePlugin } from 'esbuild-loader-svelte'
import * as sass from 'sass'

await esbuild.build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    sveltePlugin({
      generate: 'client',
      sassModule: sass,
      filterWarnings: (w) => !w.code?.startsWith('a11y'),
    }),
  ],
})

scssPlugin

Compile .scss files to CSS with automatic @import dependency resolution.

Example

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

await esbuild.build({
  entryPoints: ['src/styles/index.scss'],
  bundle: true,
  outdir: 'dist',
  plugins: [scssPlugin()],
})

rawPlugin

Import files as raw text, ideal for code display scenarios. Triggered by the ?raw suffix.

Example

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

// esbuild 配置
plugins: [rawPlugin()]

// 业务代码中
import code from './Example.svelte?raw'
console.log(code) // 文件的原始文本内容

metaPlugin

Extract Svelte component metadata including props list, source code, and compilation warnings. Triggered by the ?meta suffix.

Param

Example

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

// esbuild 配置
plugins: [metaPlugin()]

// 业务代码中
import meta from './Button.svelte?meta'
console.log(meta.props)    // [{ name, type, default }]
console.log(meta.source)   // 组件源码字符串
console.log(meta.warnings) // 编译警告数组

ssrStubPlugin

Replace browser-only modules (like DOM APIs) with stub modules during SSR builds to prevent server-side execution errors.

Param

Example

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

plugins: [
  ssrStubPlugin({
    'browser-only-lib': './stubs/browser-only.js',
  }),
]

Template Engine

Provides three functions: renderTemplate, readTemplate, and setTemplatesDir for reading and rendering template files.

API

Example

import { renderTemplate, setTemplatesDir } from 'esbuild-loader-svelte'

// 可选：自定义模板目录
setTemplatesDir('./my-templates')

// 渲染模板
const html = renderTemplate('html.html', {
  TITLE: '我的页面',
  CONTENT: '<div id="app"></div>',
})

Built-in Templates