This document explains the architecture of the main svelte package located at packages/svelte It covers how the package is organized into modular subsystems, how it uses conditional exports to deliver optimized code for different environments (browser, server, worker), and the relationships between these systems.
For information about the compilation pipeline that transforms .svelte files, see Compiler Architecture. For details on the client-side runtime system that powers reactivity and DOM updates, see Runtime System. For server-side rendering specifics, see Server-Side Rendering.
The svelte package is organized as a collection of subsystems that can be imported independently. The package uses Node.js conditional exports to provide environment-specific implementations, ensuring that browser code never ships to servers and vice versa.
packages/svelte/
├── src/
│ ├── compiler/ # Compilation pipeline (parse, analyze, transform)
│ ├── internal/
│ │ ├── client/ # Client-side runtime internals
│ │ └── server/ # Server-side rendering internals
│ ├── reactivity/ # Public reactivity APIs
│ ├── store/ # Store implementations
│ ├── animate/ # Animation utilities
│ ├── motion/ # Motion/tweening utilities
│ ├── transition/ # Transition effects
│ ├── easing/ # Easing functions
│ ├── events/ # Event handling utilities
│ ├── attachments/ # Attachment system
│ ├── legacy/ # Svelte 4 compatibility layer
│ ├── index-client.js # Main client entry point
│ └── index-server.js # Main server entry point
├── types/ # TypeScript type definitions
└── package.json # Package configuration with exports
Sources: packages/svelte/package.json1-186 packages/svelte/src/internal/client/index.js1-184 packages/svelte/src/internal/server/index.js1-476
The package uses the exports field in packages/svelte/package.json22-112 to provide different implementations based on the execution environment. This ensures optimal code delivery without unnecessary dependencies.
Sources: packages/svelte/package.json23-28
The package defines export conditions for major subsystems:
| Export Path | Browser | Server/Worker | Purpose |
|---|---|---|---|
"." | index-client.js | index-server.js | Core framework APIs |
"svelte/reactivity" | reactivity/index-client.js | reactivity/index-server.js | Reactive primitives ($state, $derived, etc.) |
"svelte/store" | store/index-client.js | store/index-server.js | Store implementations |
"svelte/compiler" | compiler/index.js | compiler/index.js | Build-time compilation |
"svelte/server" | N/A | server/index.js | SSR-only APIs (render) |
Sources: packages/svelte/package.json23-111
Some subsystems have no environment-specific behavior and export a single implementation:
| Export Path | Implementation | Purpose |
|---|---|---|
"svelte/animate" | animate/index.js | FLIP animations |
"svelte/motion" | motion/index.js | Tweened/spring stores |
"svelte/transition" | transition/index.js | Built-in transitions |
"svelte/easing" | easing/index.js | Easing functions |
"svelte/action" | Types only | Action type definitions |
"svelte/elements" | elements.d.ts | HTML/SVG element types |
"svelte/events" | events/index.js | Event utilities |
"svelte/attachments" | attachments/index.js | Attachment system |
Sources: packages/svelte/package.json33-111
The compiler is a build-time tool that transforms .svelte files into executable JavaScript. It is environment-agnostic and can run in Node.js or browser environments.
The compiler exports functions like compile(), parse(), and preprocess() for transforming Svelte components. It has no dependency on DOM or server-specific APIs.
Sources: packages/svelte/package.json41-45 packages/svelte/src/compiler/index.js1-225 packages/svelte/src/compiler/phases/2-analyze/index.js1-898
The reactivity subsystem provides the reactive primitives ($state, $derived, $effect) as runtime functions. It has environment-specific implementations because effects need to integrate differently with client-side rendering vs. server-side rendering.
On the client, these functions create signals that participate in the fine-grained reactivity system. On the server, they behave as simple function wrappers or no-ops since reactivity is not needed during SSR.
Sources: packages/svelte/package.json84-89 packages/svelte/src/internal/client/index.js108-127
The store subsystem implements the Svelte store contract with writable, readable, and derived stores. Like reactivity, it has environment-specific implementations.
On the server, stores avoid creating subscriptions to prevent memory leaks. On the client, they integrate with the reactivity system for automatic cleanup.
Sources: packages/svelte/package.json98-103
The internal client runtime (packages/svelte/src/internal/client) contains the core implementation of Svelte's client-side behavior. It is not intended for direct import by users.
Key modules within the client runtime:
| Module | Purpose |
|---|---|
reactivity/sources.js | Implements reactive sources ($state) |
reactivity/deriveds.js | Implements derived values ($derived) |
reactivity/effects.js | Implements effects ($effect) |
reactivity/batch.js | Batches updates and schedules effects |
dom/blocks/ | Implements control flow blocks ({#if}, {#each}, etc.) |
dom/elements/ | Implements element creation and attributes |
dom/elements/events.js | Event delegation and handling |
dom/elements/bindings/ | Two-way binding implementations |
dom/hydration.js | Client-side hydration logic |
context.js | Component context management |
proxy.js | State proxying for reactivity |
Sources: packages/svelte/src/internal/client/index.js1-184
The internal server runtime (packages/svelte/src/internal/server) handles server-side rendering. It generates HTML strings instead of manipulating the DOM.
Key server runtime exports:
The server runtime includes functions like render(), element(), attributes(), and helpers for stores, slots, and control flow. All output is string-based.
Sources: packages/svelte/src/internal/server/index.js1-476 packages/svelte/src/internal/server/index.js71-76
The main svelte export resolves to different entry points based on environment:
packages/svelte/src/index-client.js re-exports user-facing APIs from the internal client runtime:
index-client.js exports:
├── Component lifecycle: mount, hydrate, unmount, onMount, onDestroy
├── Reactivity: (not exported here, use svelte/reactivity)
├── Store: (not exported here, use svelte/store)
├── Context: getContext, setContext, hasContext, getAllContexts, createContext
├── Utilities: tick, flushSync, untrack
└── Legacy compatibility: SvelteComponent, createEventDispatcher, etc.
These APIs are designed for use in browser environments and depend on DOM APIs.
Sources: packages/svelte/types/index.d.ts1-610
packages/svelte/src/index-server.js exports a minimal API surface for SSR environments:
index-server.js exports:
├── mount (server variant)
├── hydrate (server variant)
└── Context APIs (for use during SSR)
The server entry point avoids exporting DOM-dependent APIs. The render() function for SSR is exported from svelte/server instead.
Sources: packages/svelte/package.json25-27
All subsystems share a common type definition file at packages/svelte/types/index.d.ts The types use module augmentation to provide correct typings regardless of which export path is used.
The type system reflects the dual nature of Svelte 5 components as functions while maintaining compatibility with Svelte 4's class-based component types through SvelteComponent and legacy helpers.
Sources: packages/svelte/types/index.d.ts3-610 packages/svelte/package.json7
The package includes a legacy compatibility layer at packages/svelte/src/legacy to support Svelte 4 component APIs in Svelte 5:
This allows gradual migration from Svelte 4 to Svelte 5 by providing createClassComponent() and asClassComponent() helpers that wrap the new function-based components in the old class-based API.
Sources: packages/svelte/package.json74-79 packages/svelte/src/legacy/legacy-client.js1-189
The package build process transforms source files and generates type definitions:
packages/svelte/package.json141 defines the build process:
build = process-messages && rollup && generate:types && check-treeshakeability
dts-buddy to generate TypeScript declaration filesSources: packages/svelte/package.json141
After building, the published package contains:
svelte/ (published)
├── src/ # Unbundled source code
├── compiler/ # Bundled compiler (CommonJS + ESM)
├── types/ # Generated TypeScript definitions
├── elements.d.ts # HTML/SVG element type definitions
├── package.json # Package metadata with exports
└── README.md # Package documentation
The package ships unbundled source in src/ (except for the compiler which is pre-bundled) to allow optimal tree-shaking by downstream build tools.
Sources: packages/svelte/package.json11-19
Within the package source, internal imports use path aliases defined in packages/svelte/package.json113-123 These aliases provide convenient access to internal modules:
| Alias | Resolves To | Purpose |
|---|---|---|
#client | internal/client/types.d.ts | Client runtime types |
#client/constants | internal/client/constants.js | Client constants |
#compiler | compiler/private.d.ts | Compiler types and functions |
#compiler/builders | compiler/utils/builders.js | AST builder utilities |
#server | internal/server/types.d.ts | Server runtime types |
#shared | internal/shared/types.d.ts | Shared types |
These imports are resolved by Node.js and bundlers but are internal-only and not exposed to package consumers.
Sources: packages/svelte/package.json113-123
The package version is managed in two places:
packages/svelte/src/version.js1-9 exports:
VERSION: The full semantic version (e.g., "5.53.0")PUBLIC_VERSION: The major version (e.g., "5")The version file is regenerated during the build process by packages/svelte/scripts/generate-version.js
Sources: packages/svelte/src/version.js1-9 packages/svelte/package.json5
Refresh this wiki