Patterns and conventions

Active contributors: Rich Harris, Simon H, Dominic Gannaway

Naming

Per CONTRIBUTING.md:

• snake_case for internal variable names and methods.
• camelCase for public (exported) variable names and methods.

You can verify this by glancing at packages/svelte/src/internal/client/runtime.js (entirely snake_case) versus packages/svelte/src/index-client.js (onMount, flushSync, getContext).

File and module layout

• One concept per file. The compiler transform visitors (packages/svelte/src/compiler/phases/3-transform/{client,server}/visitors/*.js) are the most extreme example — one file per AST node type.
• Co-locate runtime + tests when the test is unit-style: e.g., packages/svelte/src/reactivity/map.js next to map.test.ts.
• Component-level test samples live under packages/svelte/tests/<suite>/samples/<name>/main.svelte + _config.js.

Generated code

These files are fully or partially auto-generated. Hand-editing them will be reverted by CI:

File	Generator
packages/svelte/src/compiler/errors.js	packages/svelte/scripts/process-messages from messages/compile-errors/
packages/svelte/src/compiler/warnings.js	same generator from messages/compile-warnings/
packages/svelte/src/internal/client/errors.js, warnings.js	from messages/client-errors, client-warnings
packages/svelte/src/internal/server/errors.js, warnings.js	from messages/server-errors, server-warnings
packages/svelte/src/internal/shared/errors.js, warnings.js	from messages/shared-errors, shared-warnings
packages/svelte/types/index.d.ts	dts-buddy invoked from pnpm generate:types
packages/svelte/src/version.js	pnpm changeset:version (packages/svelte/scripts/generate-version.js)

Imports

• Use the workspace alias imports declared in packages/svelte/package.json#imports:
  • #client — internal/client/types.d.ts
  • #client/constants — bitmask constants
  • #compiler / #compiler/builders — compiler internals + b.statement(...) builder helpers
  • #server / #shared
• Inside internal/client/, prefer relative imports for code, and #client for types.

Error and warning emission

To add a new compile error or warning:

1. Create a markdown file under the appropriate packages/svelte/messages/<category>/ directory. The slug becomes the function name; the body becomes the message template.
2. Run pnpm dev (or pnpm generate) inside packages/svelte/ to regenerate the .js modules.
3. Import as import * as e from './errors.js' (or as w for warnings) and call e.your_new_code(arg1, arg2).

The runtime equivalents (internal/client/errors.js, etc.) follow the same workflow under messages/{client,server,shared}-errors/ and messages/*-warnings/.

Builder helpers

The compiler heavily uses b (statements) and x (expressions) builders from packages/svelte/src/compiler/utils/builders.js. A typical visitor looks like:

return b.call('$.set', context.visit(left), context.visit(right));

This keeps generated code readable and consistent. Search the visitors directory for examples.

Reactivity invariants

Maintained in packages/svelte/src/internal/client/runtime.js:

• A read in a Reaction adds the source to the reaction's deps array.
• A write to a Source increments update_version and marks dependent reactions dirty.
• Effects run inside update_effect, which sets active_reaction, active_effect, and tracks teardown.
• untrack(fn) runs fn with active_reaction = null so reads inside it are not tracked.

When in doubt, follow set_active_reaction(...) calls — they bracket every transition between tracked and untracked code.

Dev-only code

Wrap dev-only behaviour in if (DEV) { ... } (DEV from esm-env) so production bundles tree-shake it out. The dev helpers (tracing, hmr, inspect, assign, validation, ownership) are isolated under packages/svelte/src/internal/client/dev/ so a static analyser can spot any non-dev usage.

Public API stability

Anything exported from packages/svelte/src/index-client.js, index-server.js, compiler/index.js, or one of the subpath exports in packages/svelte/package.json is public. Internal types may live in *.d.ts next to the implementation but are not exported.

When introducing a public API, update:

• The relevant public.d.ts (e.g., packages/svelte/src/transition/public.d.ts).
• A changeset (npx changeset).
• packages/svelte/src/index.d.ts if it surfaces at the top level.