Svelte 5 Codebase Architecture: A Map for the Territory

Most frameworks are either compilers or runtimes. Svelte is both. A .svelte file goes through a compiler that produces optimized JavaScript, and that JavaScript calls into a runtime that manages reactivity, DOM updates, and lifecycle. Understanding this duality — and the contract between the two halves — is the key to reading the Svelte codebase. This article gives you the mental model.

Monorepo Structure and Package Layout

The Svelte repository is a monorepo, but an unusual one: it ships a single npm package. The packages/svelte directory contains the compiler, runtime, public APIs, and all supporting infrastructure. Everything else — playgrounds, documentation scaffolding, benchmarks — lives at the repository root or in sibling directories.

Here's the directory map for the core package:

Path	Purpose
packages/svelte/src/compiler/	Three-phase compiler: parse → analyze → transform
packages/svelte/src/internal/client/	Client-side runtime (reactivity, DOM, effects)
packages/svelte/src/internal/server/	Server-side runtime (SSR renderer, context)
packages/svelte/src/internal/flags/	Feature flags for tree shaking
packages/svelte/src/reactivity/	Public reactive utilities (SvelteDate, SvelteSet, etc.)
packages/svelte/src/store/	Svelte 4 store compatibility layer
packages/svelte/src/index-client.js	Public client API entry point
packages/svelte/src/index-server.js	Public server API entry point
packages/svelte/messages/	Markdown-defined error/warning messages
packages/svelte/scripts/	Build scripts (message processing, type generation)

The packages/svelte/package.json defines the package as "type": "module" and declares an extensive exports map — the mechanism that makes the entire client/server split work.

The Dual Nature: Compiler + Runtime

Svelte's architecture can be summarized in one sentence: the compiler writes code that calls the runtime. When you write let count = $state(0), the compiler transforms that into a call to $.state(0), where $ is the internal runtime module imported as import * as $ from 'svelte/internal/client'.

flowchart LR
    A[".svelte file"] --> B["Compiler<br/>(parse → analyze → transform)"]
    B --> C["JavaScript module<br/>(import * as $ from 'svelte/internal/client')"]
    C --> D["Runtime<br/>($.state, $.effect, $.if, $.each, ...)"]
    D --> E["DOM"]

The compiler entry point at packages/svelte/src/compiler/index.js exposes four public functions: compile(), compileModule(), parse(), and migrate(). The compile() function orchestrates the three-phase pipeline — parse, analyze, transform — and returns a CompileResult with JavaScript code, a source map, CSS output, and warnings.

The runtime entry point at packages/svelte/src/internal/client/index.js is a massive barrel file that re-exports over 100 functions. These are the "ABI" — the application binary interface that compiled output depends on. Every $.if(), $.each(), $.state(), $.derived() call in compiled code resolves to an export from this file.

Tip: When you see compiled Svelte output referencing $.something(), search for the corresponding export in src/internal/client/index.js to find the actual implementation.

Conditional Exports and the Client/Server Split

The exports map in package.json is where Svelte's environment-aware design becomes visible. Look at the root entry point:

".": {
  "types": "./types/index.d.ts",
  "worker": "./src/index-server.js",
  "browser": "./src/index-client.js",
  "default": "./src/index-server.js"
}

When a bundler resolves import { mount } from 'svelte', it selects the correct file based on the target environment. Browser bundles get index-client.js; Node.js/SSR environments get index-server.js. This pattern repeats across sub-paths: svelte/store, svelte/reactivity, and svelte/legacy all have their own client/server splits.

flowchart TD
    Import["import { mount } from 'svelte'"]
    Import -->|"browser condition"| Client["index-client.js<br/>Real mount(), hydrate(), onMount()"]
    Import -->|"default condition"| Server["index-server.js<br/>Stubs: mount() throws, onMount = noop"]

The server entry point at packages/svelte/src/index-server.js is instructive. Functions like onMount, beforeUpdate, and afterUpdate are exported as noop — they simply do nothing on the server. Functions like mount() and hydrate() throw an error because calling them during SSR is a bug. Meanwhile, onDestroy actually works on the server (it hooks into the SSR renderer), and context functions (getContext, setContext) have real server implementations.

The client entry at packages/svelte/src/index-client.js shows a more nuanced story. onMount in runes mode creates a user_effect — it's implemented on top of the new signal-based effect system rather than being its own primitive.

This same conditional pattern applies to the internal modules. The compiler generates different output for client vs. server targets, importing from svelte/internal/client or svelte/internal/server respectively.

The Internal Runtime ABI

The packages/svelte/src/internal/client/index.js file is the contract surface between compiled code and the runtime. It exports functions organized by category:

Category	Examples	Source
Control flow blocks	if_block, each, await_block, key	dom/blocks/*.js
Template creation	from_html, from_tree, from_svg, text	dom/template.js
Reactivity primitives	state, derived, effect, render_effect	reactivity/*.js
DOM operations	set_attribute, set_class, set_style	dom/elements/*.js
Bindings	bind_value, bind_checked, bind_this	dom/elements/bindings/*.js
Component lifecycle	push, pop, init	context.js, dom/legacy/lifecycle.js
Transitions	transition, animation	dom/elements/transitions.js

The key import in every compiled component looks like this:

import * as $ from 'svelte/internal/client';

This namespace import means bundlers can tree-shake unused functions. If your component doesn't use {#each}, the $.each() implementation gets eliminated from the final bundle.

graph TD
    subgraph "Compiled Component"
        A["$.state(0)"]
        B["$.template_effect(...)"]
        C["$.if(node, fn)"]
    end
    subgraph "svelte/internal/client"
        D["sources.js → state()"]
        E["effects.js → template_effect()"]
        F["blocks/if.js → if_block()"]
    end
    A --> D
    B --> E
    C --> F

Feature Flags and Dead Code Elimination

Svelte 5 has three feature flags defined in packages/svelte/src/internal/flags/index.js:

export let async_mode_flag = false;   // experimental.async=true
export let legacy_mode_flag = false;  // Svelte 4 compatibility
export let tracing_mode_flag = false; // $inspect.trace debugging

These are module-level let bindings — false by default. The compiler generates imports that enable them when needed. For example, if a project contains Svelte 4 components, the compiled output includes import 'svelte/internal/flags/legacy', which calls enable_legacy_mode_flag(), setting the boolean to true.

flowchart LR
    Compiler["Compiler detects<br/>legacy component"] --> Import["Generated: import 'svelte/internal/flags/legacy'"]
    Import --> Enable["enable_legacy_mode_flag()<br/>legacy_mode_flag = true"]
    Enable --> Runtime["Runtime code paths:<br/>if (legacy_mode_flag) { ... }"]

The brilliance is in the tree-shaking: if legacy_mode_flag is never set to true, a bundler can determine that branches guarded by if (legacy_mode_flag) are dead code and eliminate them. This means a pure Svelte 5 project pays no bundle cost for Svelte 4 compatibility code.

Tip: If you're investigating a runtime code path and see a flag guard like if (legacy_mode_flag && ...), you can usually skip that branch when studying the modern Svelte 5 behavior.

Markdown-Driven Error and Warning Messages

Every error and warning in Svelte — compiler diagnostics, client runtime errors, server errors — is defined in Markdown files under packages/svelte/messages/. For example, messages/compile-errors/template.md contains entries like:

## animation_duplicate

> An element can only have one 'animate' directive

The build script at packages/svelte/scripts/process-messages/index.js reads these Markdown files and generates JavaScript modules with exported functions. Each error code becomes a callable function: e.animation_duplicate(node).

flowchart TD
    MD["messages/compile-errors/template.md"] --> Script["scripts/process-messages/index.js"]
    Script --> JS["src/compiler/errors.js<br/>(generated)"]
    Script --> Docs["documentation/.generated/<br/>compile-errors.md"]
    JS --> Compiler["Compiler calls e.animation_duplicate()"]

This approach has three significant benefits:

1. Single source of truth — the error message text, code, and documentation all come from one Markdown file
2. Consistent format — every error follows the same structure (code, message, optional details)
3. Auto-generated docs — the same Markdown is transformed into documentation pages

The message categories mirror the codebase structure: compile-errors, compile-warnings, client-errors, client-warnings, server-errors, server-warnings, and shared variants.

Build System and Testing Overview

The build pipeline is simple. The compiler is bundled with Rollup into a CommonJS module (for Node.js consumption via require()). The runtime ships as raw ES modules — no bundling needed, since downstream tools handle that.

Testing uses Vitest with a configuration at vitest.config.js that sets up module resolution to mirror the conditional exports. The test suite includes:

Test Category	What It Tests
runtime-runes	Svelte 5 runes-based component behavior
runtime-legacy	Svelte 4 compatibility mode
compiler-errors	Expected compilation failures
compiler-warnings	Expected diagnostic warnings
hydration	Client/server rendering agreement
signals	Low-level reactivity engine
snapshot	Compiled output stability

flowchart LR
    Test["vitest"] --> Resolve["Custom resolver:<br/>maps 'svelte/' imports<br/>to correct client/server files"]
    Resolve --> Client["Browser tests<br/>→ src/index-client.js"]
    Resolve --> Server["SSR tests<br/>→ src/index-server.js"]

The customResolver in the Vitest config intelligently routes svelte/* imports to either client or server files based on whether the test path contains _output/server.

What's Next

With this map in hand, we're ready to follow a .svelte file through the compiler pipeline. In the next article, we'll trace how the Svelte compiler parses source code into an AST with a hand-written state machine parser, analyzes that AST to resolve bindings and detect runes, and then transforms it into the JavaScript output that imports all those $.xxx functions we just surveyed.