Preprocess

Active contributors: Rich Harris, Ben McCann, Simon H

Purpose

preprocess(source, transformers, options) runs user-supplied per-language transforms on a .svelte file's <script>, <style>, and markup before the compiler ever sees it. Tooling integrations (vitePreprocess, mdsvex, etc.) plug TypeScript, SCSS, PostCSS, MDX-style syntax, and similar in via this hook.

The implementation is small and self-contained:

• Public entry: packages/svelte/src/compiler/preprocess/index.js
• Source-map plumbing: packages/svelte/src/compiler/preprocess/decode_sourcemap.js, replace_in_code.js
• Public types: packages/svelte/src/compiler/preprocess/public.d.ts, legacy-public.d.ts
• Re-exported via svelte/compiler#preprocess from packages/svelte/src/compiler/index.js

API shape

A preprocessor is an object with up to four keys: name, markup, script, style. Each one is an async function that takes { content, attributes, filename, markup } and returns { code, map?, attributes? } (or void to leave the input unchanged).

The runtime applies each transformer in order:

1. markup runs first on the entire file.
2. For each <script> block, every transformer's script runs in order.
3. For each <style> block, every transformer's style runs in order.
4. Source maps from each step are concatenated and remapped against the original.

packages/svelte/src/compiler/preprocess/index.js (~10 KB) implements all of this in roughly 300 lines, including detecting multiple <script> and <style> blocks, dispatching by language attribute, and composing source maps via @jridgewell/sourcemap-codec and @jridgewell/remapping (declared in packages/svelte/package.json).

Source-map handling

decode_sourcemap.js decodes a third-party tool's source map into a typed structure. replace_in_code.js then performs the in-place replacement while threading mappings through. The end result is a single source map that links every character in the post-preprocess source back to its origin in the user's .svelte file.

Tests

packages/svelte/tests/preprocess/ covers this. Each sample provides a series of fake transformers and asserts the post-preprocess code and map.

Backwards compatibility

legacy-public.d.ts preserves the older preprocessor signature in which markup returned a single object instead of { code, map, dependencies }. New code should use the modern signature documented in public.d.ts.

See also

• Compiler — what compile() does after preprocess.
• Tooling — where preprocess fits in the build pipeline (Rollup, Vite).