Analysis Phase

Relevant source files

• documentation/docs/07-misc/04-custom-elements.md
• documentation/docs/98-reference/.generated/compile-errors.md
• packages/svelte/messages/compile-errors/script.md
• packages/svelte/messages/compile-errors/template.md
• packages/svelte/src/ambient.d.ts
• packages/svelte/src/compiler/errors.js
• packages/svelte/src/compiler/index.js
• packages/svelte/src/compiler/phases/1-parse/index.js
• packages/svelte/src/compiler/phases/1-parse/read/options.js
• packages/svelte/src/compiler/phases/1-parse/state/element.js
• packages/svelte/src/compiler/phases/1-parse/state/tag.js
• packages/svelte/src/compiler/phases/2-analyze/index.js
• packages/svelte/src/compiler/phases/2-analyze/types.d.ts
• packages/svelte/src/compiler/phases/2-analyze/visitors/CallExpression.js
• packages/svelte/src/compiler/phases/2-analyze/visitors/IfBlock.js
• packages/svelte/src/compiler/phases/2-analyze/visitors/RenderTag.js
• packages/svelte/src/compiler/phases/3-transform/client/transform-client.js
• packages/svelte/src/compiler/phases/3-transform/client/types.d.ts
• packages/svelte/src/compiler/phases/3-transform/client/utils.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/BindDirective.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/EachBlock.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/Fragment.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/HtmlTag.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/IfBlock.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/KeyBlock.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/RegularElement.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/RenderTag.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/SlotElement.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/SvelteElement.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/shared/component.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/shared/element.js
• packages/svelte/src/compiler/phases/3-transform/client/visitors/shared/utils.js
• packages/svelte/src/compiler/phases/3-transform/server/transform-server.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/IfBlock.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/RegularElement.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/SlotElement.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/SvelteElement.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/shared/component.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/shared/element.js
• packages/svelte/src/compiler/phases/3-transform/server/visitors/shared/utils.js
• packages/svelte/src/compiler/phases/nodes.js
• packages/svelte/src/compiler/phases/scope.js
• packages/svelte/src/compiler/phases/types.d.ts
• packages/svelte/src/compiler/types/index.d.ts
• packages/svelte/src/compiler/types/template.d.ts
• packages/svelte/src/compiler/validate-options.js
• packages/svelte/src/constants.js
• packages/svelte/src/index.d.ts
• packages/svelte/src/internal/client/dom/blocks/branches.js
• packages/svelte/src/internal/client/dom/elements/attributes.js
• packages/svelte/src/internal/client/index.js
• packages/svelte/src/internal/flags/index.js
• packages/svelte/src/internal/server/index.js
• packages/svelte/src/legacy/legacy-client.js
• packages/svelte/tests/runtime-browser/custom-elements-samples/closed-shadow-dom/_config.js
• packages/svelte/tests/runtime-legacy/samples/dynamic-element-invalid-this-content/_config.js
• packages/svelte/tests/runtime-legacy/samples/dynamic-element-invalid-this-content/main.svelte
• packages/svelte/tests/runtime-legacy/shared.ts
• packages/svelte/tests/runtime-runes/samples/async-attach-hydration-mismatch/Inner.svelte
• packages/svelte/tests/runtime-runes/samples/async-attach-hydration-mismatch/Outer.svelte
• packages/svelte/tests/runtime-runes/samples/async-attach-hydration-mismatch/Trigger.svelte
• packages/svelte/tests/runtime-runes/samples/async-attach-hydration-mismatch/_config.js
• packages/svelte/tests/runtime-runes/samples/async-if-nested/_config.js
• packages/svelte/tests/runtime-runes/samples/async-if-nested/main.svelte
• packages/svelte/tests/runtime-runes/samples/snippet-const/_config.js
• packages/svelte/tests/runtime-runes/samples/snippet-const/main.svelte
• packages/svelte/tests/snapshot/samples/await-block-scope/_expected/server/index.svelte.js
• packages/svelte/tests/types/component.ts
• packages/svelte/tests/validator/samples/const-tag-placement-1/errors.json
• packages/svelte/tests/validator/samples/const-tag-placement-2/errors.json
• packages/svelte/tests/validator/samples/tag-non-string/errors.json
• packages/svelte/types/index.d.ts

The Analysis Phase is Phase 2 of the Svelte compiler pipeline. It performs semantic analysis on the parsed AST from Phase 1, producing a ComponentAnalysis object that contains all metadata needed for Phase 3 (Transformation).

For information about how source code is parsed into an AST, see Parsing Phase. For information about how the analysis output is transformed into executable code, see Transformation Phase.

Overview

The Analysis Phase processes the output of parse() and produces structured metadata about the component:

Scope Analysis:

• Creates scope hierarchy for module, instance, and template contexts
• Tracks variable declarations and references across scopes
• Implements lexical scoping rules with proper shadowing

Binding Classification:

• Determines binding kind for each variable ('state', 'derived', 'prop', 'normal', etc.)
• Identifies which bindings need reactive wrappers
• Tracks reassignment and mutation patterns

Mode Detection:

• Determines runes mode vs legacy mode based on syntax usage
• Detects rune function calls ($state(), $derived(), $effect(), $props())
• Validates rune usage and placement

Dependency Tracking:

• Builds dependency graphs for reactive statements (legacy mode)
• Calculates blockers for async top-level statements
• Analyzes CSS selector usage and scoping

Validation:

• Reports errors for invalid syntax patterns
• Warns about potential reactivity issues
• Validates directive usage and component structure

The analysis phase has two entry points:

• analyze_component(root, source, options) - Analyzes .svelte component files packages/svelte/src/compiler/phases/2-analyze/index.js330-935
• analyze_module(source, options) - Analyzes .js/.ts module files with runes packages/svelte/src/compiler/phases/2-analyze/index.js256-322

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js1-1076 packages/svelte/src/compiler/types/index.d.ts1-328

Entry Points and Core Functions

Diagram: Analysis Phase Entry Points and Data Flow

Core Analysis Functions:

Function	Location	Purpose
analyze_component()	2-analyze/index.js330-935	Main entry for .svelte files; analyzes module, instance, and template
analyze_module()	2-analyze/index.js256-322	Entry for .js/.ts files with runes
create_scopes()	scope.js865-1390	Builds scope hierarchy by walking AST
js()	2-analyze/index.js215-233	Helper creating Js object with scope metadata
get_rune()	scope.js1392-1495	Identifies rune calls in expressions
calculate_blockers()	2-analyze/index.js946-1076	Computes async statement dependencies

Key Classes:

• Binding scope.js88-196 - Represents a variable declaration with usage tracking
• Scope scope.js605-798 - Manages declarations and references in a lexical scope
• ScopeRoot scope.js800-863 - Root scope manager with conflict tracking
• Evaluation scope.js198-603 - Partial evaluation of expressions for optimization

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js215-1076 packages/svelte/src/compiler/phases/scope.js88-1495

Core Data Structures

Binding Class

The Binding class scope.js88-196 represents a variable declaration with usage tracking. Each Binding is created when a variable is declared and accumulates information as the analyzer encounters references.

Diagram: Binding Class Structure

Binding Kinds (defined in scope.js88-196):

Kind	Created By	Usage in Transform
'normal'	Regular let/const/var	No reactive wrapper
'state'	$state() call	Wrapped in $.mutable_source()
'raw_state'	$state.raw() call	Wrapped in $.mutable_source() (no proxy)
'derived'	$derived() or $derived.by()	Wrapped in $.derived()
'prop'	$props() destructuring	Wrapped in $.prop()
'bindable_prop'	$props() with $bindable()	Wrapped in $.prop() with PROPS_IS_BINDABLE
'rest_prop'	$$props, $$restProps	Special handling for legacy compat
'store_sub'	$storeName reference	Synthetic binding for store subscription
'each'	Each block variables	Block-scoped iteration binding
'snippet'	{#snippet name(...)}	Function declaration
'legacy_reactive'	$: x = ... (legacy)	Wrapped in $.mutable_source()

Key Properties:

• mutated - Set to true if binding is mutated (e.g., obj.prop = x)
• reassigned - Set to true if binding is reassigned (e.g., x = 5)
• updated - Getter returning mutated || reassigned
• blocker - For async dependencies, points to $$blockers[n] expression

Sources: packages/svelte/src/compiler/phases/scope.js88-196

Scope Class

The Scope class represents a lexical scope and manages declarations and references:

Key Methods:

• declare() - Creates a new binding in this scope packages/svelte/src/compiler/phases/scope.js659-686
• get() - Looks up a binding by name (searches parent scopes) packages/svelte/src/compiler/phases/scope.js723-725
• owner() - Finds which scope owns a declaration packages/svelte/src/compiler/phases/scope.js743-745
• reference() - Records a reference to an identifier packages/svelte/src/compiler/phases/scope.js751-768
• evaluate() - Performs partial evaluation of expressions packages/svelte/src/compiler/phases/scope.js778-783

Sources: packages/svelte/src/compiler/phases/scope.js591-784

Analysis Process Flow

Process Steps in analyze_component():

1. Initialize Scope Hierarchy 2-analyze/index.js331-344

   • Create ScopeRoot instance
   • Call js() helper for module script → module.scope
   • Call js() helper for instance script (parent: module.scope) → instance.scope
   • Call create_scopes() for template (parent: instance.scope) → template.scope

2. Handle Store Subscriptions 2-analyze/index.js348-445

   • Scan module scope for $storeName references
   • Create synthetic 'store_sub' bindings in instance scope
   • Validate not used in nested scopes or module script
   • Handle legacy mode vs runes mode differences

3. Detect Runes Mode 2-analyze/index.js449-457

4. Walk Module/Instance/Template ASTs 2-analyze/index.js705-793

   • Use walk() from zimmerframe with visitor object
   • Each visitor updates AnalysisState and ComponentAnalysis
   • Classify bindings, track references, validate usage

5. Process Exports and Props 2-analyze/index.js563-616

   • In legacy mode: convert export let to bindable_prop
   • In runes mode: track exports for component API

6. Order Reactive Statements (legacy only) 2-analyze/index.js810

   • Build dependency graph for $: statements
   • Topologically sort for correct execution order

7. Calculate Async Blockers 2-analyze/index.js693

   • For top-level await, compute which bindings depend on which

8. Validate and Report Errors 2-analyze/index.js813-852

   • Check for mixed event handler syntaxes
   • Validate snippet exports and usage
   • Check slot vs snippet conflicts

9. Analyze CSS 2-analyze/index.js855-872

   • Call analyze_css() for selector analysis
   • Call prune() to mark scoped elements
   • Call warn_unused() for unused selector warnings

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js330-935

Visitor Pattern and AST Traversal

The analysis phase uses the visitor pattern via zimmerframe.walk() to traverse the AST. Each node type has a corresponding visitor function.

Key Visitors:

Visitor	Purpose	File
_	Base visitor, handles scope switching	2-analyze/index.js93-145
Identifier	Tracks references, validates usage	visitors/Identifier.js
CallExpression	Detects rune calls, validates arguments	visitors/CallExpression.js1-263
VariableDeclarator	Detects state declarations, classifies bindings	visitors/VariableDeclarator.js
ExportNamedDeclaration	Handles prop exports in legacy mode	visitors/ExportNamedDeclaration.js
Component	Analyzes component usage, props, bindings	visitors/Component.js
EachBlock	Creates each block scopes, validates	visitors/EachBlock.js
BindDirective	Validates bindings, marks mutated bindings	visitors/BindDirective.js

AnalysisState Structure:

Each visitor receives an AnalysisState object 2-analyze/types.d.ts1-45 containing:

This state is threaded through all visitors and updated as the traversal progresses. The scope field changes as the traversal enters/exits lexical scopes, while analysis accumulates metadata throughout.

Sources: packages/svelte/src/compiler/phases/2-analyze/types.d.ts1-45 packages/svelte/src/compiler/phases/2-analyze/index.js92-206

Rune Detection and Classification

Runes are special function calls that declare reactive state. The analysis phase detects these and classifies their bindings accordingly.

Rune Detection Process:

The get_rune() function scope.js1392-1495 identifies rune calls by analyzing CallExpression nodes:

Classification by Rune:

Rune Call	Binding Kind	Created In Visitor
$state(value)	'state'	VariableDeclarator
$state.raw(value)	'raw_state'	VariableDeclarator
$derived(expr)	'derived'	VariableDeclarator
$derived.by(fn)	'derived'	VariableDeclarator
$props()	Multiple 'prop'	VariableDeclarator
$bindable(fallback)	Marks as 'bindable_prop'	Inside $props()
$effect(fn)	No binding	ExpressionStatement
$effect.pre(fn)	No binding	ExpressionStatement
$effect.tracking()	No binding	Returns boolean
$effect.root(fn)	No binding	Returns cleanup function
$inspect(...)	No binding	Dev-only inspection

Validation Rules:

The CallExpression visitor 2-analyze/visitors/CallExpression.js1-263 enforces:

• $effect() must be used as expression statement only (not assigned to variable)
• $bindable() can only appear inside $props() destructuring
• State runes must be at component instance top level (not in functions/blocks)
• In module context, runes only allowed if options.runes or analysis.runes is true

Sources: packages/svelte/src/compiler/phases/scope.js1392-1495 packages/svelte/src/compiler/phases/2-analyze/visitors/CallExpression.js1-263 packages/svelte/src/compiler/phases/2-analyze/visitors/VariableDeclarator.js1-350

Legacy Mode vs Runes Mode

The analyzer behaves differently based on whether the component uses runes or legacy reactive syntax.

Detection Logic: packages/svelte/src/compiler/phases/2-analyze/index.js449-457

Legacy Mode Specific Analysis:

1. Export Let Props - Convert export let to bindable_prop bindings packages/svelte/src/compiler/phases/2-analyze/index.js563-616
2. Reactive Statements - Process $: labeled statements packages/svelte/src/compiler/phases/2-analyze/index.js618-673
3. Synthetic Props - Create $$props and $$restProps bindings packages/svelte/src/compiler/phases/2-analyze/index.js770-771
4. Implicit State - Mark reassigned variables as state packages/svelte/src/compiler/phases/2-analyze/index.js620-636

Runes Mode Specific Analysis:

1. Validate Props - Check $$props is not used packages/svelte/src/compiler/phases/2-analyze/index.js695-703
2. Non-Reactive Warnings - Warn about reassigned non-state variables packages/svelte/src/compiler/phases/2-analyze/index.js728-768
3. Explicit Everything - All reactivity must use runes

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js449-810

Store Subscriptions (Legacy Feature)

In legacy mode, references to $storeName create synthetic bindings for automatic store subscriptions.

Process:

1. Detect $storeName references in module scope packages/svelte/src/compiler/phases/2-analyze/index.js349-444

2. Validate:

   • Store binding exists in instance scope
   • Not shadowed by nested scope
   • Not used in module script

3. Create Synthetic Binding:

   • kind = 'store_sub'
   • declaration_kind = 'synthetic'
   • References transferred from module scope to instance scope

4. Special Cases:

   • If runes mode and rune name, treat as rune not store
   • If $derived imported from 'svelte/store', allow both usages

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js348-445

Dependency Analysis and Blockers

For async top-level statements, the analyzer calculates which bindings need to wait for which statements to complete.

Purpose: When a component has await at the instance top level, later bindings may depend on async results. The analyzer builds a dependency chain so the transform phase can inject proper awaits.

Algorithm: packages/svelte/src/compiler/phases/2-analyze/index.js946-1076

1. Walk through all top-level statements in order
2. For each statement with await, mark as a blocker
3. Recursively track which bindings reference async bindings
4. Assign blocker indices to dependent bindings

Result: Each binding gets a blocker property (a MemberExpression like $$blockers[0]) that the transform phase will use to generate await expressions.

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js937-1076

ComponentAnalysis Output Structure

The analyze_component() function returns a ComponentAnalysis object types/index.d.ts60-127 that contains all metadata needed for the Transformation Phase.

Diagram: ComponentAnalysis Structure

Key ComponentAnalysis Properties:

Property	Type	Purpose
name	string	Component name from get_component_name(filename)
root	ScopeRoot	Root scope with conflict tracking
module	Js	Module script scope/AST/metadata
instance	Js	Instance script scope/AST/metadata
template	Template	Template scope/AST/metadata
runes	boolean	Component uses runes mode
maybe_runes	boolean	Heuristic: might be accidental runes usage
immutable	boolean	Component declared immutable
exports	Export[]	{ name, alias } for exported identifiers
accessors	boolean	Should generate accessors
custom_element	boolean	Is custom element
inject_styles	boolean	Inject styles at runtime
elements	RegularElement[]	All HTML elements (for CSS)
css	CssAnalysis	CSS hash, keyframes, scoping info
reactive_statements	Map	Legacy $: statements (ordered)
binding_groups	Map	Groups for bind:group
slot_names	Map<string, number>	Slot name → source position
snippet_renderers	Map	Snippet render tags info
uses_props	boolean	References $$props
uses_rest_props	boolean	References $$restProps
uses_slots	boolean	References $$slots
uses_component_bindings	boolean	Has component bindings
uses_render_tags	boolean	Uses {@render}
needs_context	boolean	Needs context stack
async_deriveds	Set<Binding>	Async derived states

Js Object Structure 2-analyze/index.js215-233:

Template Object Structure:

This structure is used by:

• client_component() 3-transform/client/transform-client.js146-545 - Client-side code generation
• server_component() 3-transform/server/transform-server.js92-372 - Server-side code generation

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js215-560 packages/svelte/src/compiler/types/index.d.ts60-127 packages/svelte/src/compiler/phases/3-transform/client/transform-client.js146-210

CSS Analysis Integration

If the component has a <style> block, the analysis phase performs CSS analysis to determine selector usage and scoping.

Process:

1. Analyze CSS - Parse and validate CSS rules packages/svelte/src/compiler/phases/2-analyze/css/css-analyze.js
2. Prune Selectors - For each element, check which CSS rules apply packages/svelte/src/compiler/phases/2-analyze/css/css-prune.js
3. Mark Scoped - Elements matched by non-global selectors get metadata.scoped = true
4. Mark Dynamic - Scoped custom elements need dynamic rendering packages/svelte/src/compiler/phases/2-analyze/index.js875-877
5. Warn Unused - Issue warnings for unused selectors packages/svelte/src/compiler/phases/2-analyze/css/css-warn.js

CSS Hash Calculation: packages/svelte/src/compiler/phases/2-analyze/index.js538-544

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js854-929 packages/svelte/src/compiler/phases/2-analyze/css/css-analyze.js packages/svelte/src/compiler/phases/2-analyze/css/css-prune.js

Validation and Error Checking

Throughout analysis, the phase validates component structure and reports errors:

Key Validations:

1. Rune Placement packages/svelte/src/compiler/phases/2-analyze/visitors/CallExpression.js1-263

   • $effect() must be expression statement
   • $bindable() only in $props()
   • State runes only at component instance top level

2. Binding Validation packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js

   • Cannot bind to constants
   • Cannot bind to each item in runes mode
   • Cannot bind to derived values

3. Conflict Detection packages/svelte/src/compiler/phases/2-analyze/index.js829-852

   • Mixed on:event and onevent attribute usage
   • Slots vs snippets conflict
   • Duplicate exports
   • Invalid snippet exports

4. Scope Validation packages/svelte/src/compiler/phases/2-analyze/index.js377-396

   • Store subscriptions not in nested scopes
   • Store subscriptions not in module script

5. Non-Reactive Warnings packages/svelte/src/compiler/phases/2-analyze/index.js728-768

   • Reassigned non-state variables referenced in template

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js695-852 packages/svelte/src/compiler/phases/2-analyze/visitors/CallExpression.js1-263 packages/svelte/src/compiler/phases/2-analyze/visitors/BindDirective.js

Summary

The Analysis Phase bridges parsing and code generation by:

1. Building Scopes - Creating a hierarchy of lexical scopes with proper parent relationships
2. Classifying Bindings - Determining the reactivity kind of every variable (state, derived, prop, normal, etc.)
3. Detecting Patterns - Identifying runes, reactive statements, store subscriptions, and exports
4. Analyzing Dependencies - Building dependency graphs for reactive statements and async blockers
5. Validating Structure - Checking for errors and issuing warnings
6. Preparing Metadata - Creating the ComponentAnalysis object with all information needed for code generation

The output ComponentAnalysis is consumed by the Transformation Phase to generate optimized JavaScript that implements the component's reactive behavior.

Sources: packages/svelte/src/compiler/phases/2-analyze/index.js1-935 packages/svelte/src/compiler/phases/scope.js1-1495