esbuild-loader-svelte

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

中文文档

Features

• sveltePlugin — Compile .svelte files with TypeScript and SCSS preprocessing
• scssPlugin — Compile .scss files to CSS
• ssrStubPlugin — Replace browser-specific modules with stubs during SSR builds (uses external template files)
• rawPlugin — Import files as raw text (?raw suffix) for code display
• metaPlugin — Extract Svelte component metadata (?meta suffix) including props, source code, etc.
• obfuscatorPlugin — JavaScript code obfuscation with RC4 encryption, control flow flattening
• renderTemplate / readTemplate — Template engine for reading and rendering {{KEY}} placeholder templates
• Compatible with CommonJS and ES Modules
• Supports Svelte 5 Runes mode

Installation

npm install esbuild-loader-svelte esbuild svelte --save-dev
# SCSS support (optional)
npm install sass --save-dev
# Code obfuscation (optional)
npm install javascript-obfuscator --save-dev

Usage

Full Import

import {
    sveltePlugin, scssPlugin, ssrStubPlugin,
    rawPlugin, metaPlugin,
    renderTemplate, readTemplate, setTemplatesDir
} from 'esbuild-loader-svelte'
import esbuild from 'esbuild'

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

On-Demand Import

import { sveltePlugin } from 'esbuild-loader-svelte/svelte'
import { scssPlugin } from 'esbuild-loader-svelte/scss'
import { rawPlugin } from 'esbuild-loader-svelte/raw'
import { metaPlugin } from 'esbuild-loader-svelte/meta'
import { obfuscatorPlugin } from 'esbuild-loader-svelte/obfuscator'
import { renderTemplate } from 'esbuild-loader-svelte/templates'

CommonJS

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

API

sveltePlugin(options?)

Compiles .svelte files to JavaScript.

scssPlugin(options?)

Compiles .scss files to CSS.

ssrStubPlugin(stubPaths)

Replaces specified module paths with empty stubs during SSR builds. Stub code comes from external template files (src/templates/).

// Example: skip router and heavy components during SSR
ssrStubPlugin(['src/router', 'views/HeavyComponent'])

rawPlugin()

Import files as raw text for code display scenarios.

// Build config
plugins: [rawPlugin()]

// Usage: import via ?raw suffix
import buttonCode from './Button.svelte?raw'
// buttonCode is the full source code string of Button.svelte

metaPlugin(options?)

Extracts Svelte component metadata including props, source code, and compile warnings.

// Build config
plugins: [metaPlugin()]

// Usage: import via ?meta suffix
import meta from './Button.svelte?meta'
// meta = {
//   filename: 'Button.svelte',
//   source: 'full source code',
//   props: ['type', 'size', 'disabled', ...],
//   warnings: [...],
//   metadata: { ... }
// }

obfuscatorPlugin(options?)

Obfuscates JavaScript output with RC4 encryption, control flow flattening, and dead code injection. Requires javascript-obfuscator as an optional dependency.

import { obfuscatorPlugin } from 'esbuild-loader-svelte/obfuscator'

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

renderTemplate(name, vars)

Reads a template file and replaces {{KEY}} placeholders.

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

const html = renderTemplate('html.html', {
    TITLE: 'Page Title',
    JS_FILE: 'main.abc123.js',
    CSS_LINK: '<link rel="stylesheet" href="./assets/style.css" />',
    SSR_HEAD: '',
    SSR_BODY: '<div>Pre-rendered content</div>',
})

readTemplate(name)

Reads template file content without placeholder replacement.

setTemplatesDir(dir)

Sets a custom template directory to override default templates.

import { setTemplatesDir } from 'esbuild-loader-svelte'
setTemplatesDir('/path/to/my/templates')

Built-in Template Files

License

MIT