docs: add developer guide #16517

paoloricciuti · 2025-07-28T17:44:13Z

This adds a developer guide document, a in depth guite to the svelte internals that should help people interested to contributing to better understand where to start.

Still a big draft but publishing it to get feedback.

Rendered version

Before submitting the PR, please make sure you do the following

It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
Prefix your PR title with feat:, fix:, chore:, or docs:.
This message body should clearly illustrate what problems it solves.
Ideally, include a test that fails without this PR but passes with it.
If this PR changes code within packages/svelte/src, add a changeset (npx changeset).

Tests and linting

Run the tests with pnpm test and lint the project with pnpm lint

changeset-bot · 2025-07-28T17:44:17Z

⚠️ No Changeset found

Latest commit: 2d0822b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-07-28T17:44:26Z

Playground

pnpm add https://pkg.pr.new/svelte@16517

svelte-docs-bot · 2025-07-28T17:44:40Z

Preview: https://svelte-dev-git-preview-svelte-16517-svelte.vercel.app/

DEVELOPER_GUIDE.md

benmccann · 2025-08-03T21:04:10Z

DEVELOPER_GUIDE.md

+
+Parsing is the first step to convert the component into a runnable JS file. Your `svelte` component is effectively a string and while we could try to do something with regexes and replacements the standard way to do manipulation is to first build an Abstract Syntax Tree and then manipulate that. An Abstract Syntax Tree (AST from now on) is a structured representation of code. Each language has its own syntax and relative AST (based on the parser used). Every JavaScript part of a `svelte` component, be it the script tag or an expression tag in your template, is parsed with `acorn` (`acorn-typescript` in case you use `lang="ts"`) to produce an ESTree compatible tree.
+
+If you want a more in-depth explanation of how a Parser works, you can refer to [this video](https://www.youtube.com/watch?v=mwvyKGw2CzU) by @tanhauhau where he builds a mini svelte 4 from scratch, but the gist of it is that you can basically have three main operations during the parsing phase: `eat`, `read` and `match` (with some variations).


Suggested change

If you want a more in-depth explanation of how a Parser works, you can refer to [this video](https://www.youtube.com/watch?v=mwvyKGw2CzU) by @tanhauhau where he builds a mini svelte 4 from scratch, but the gist of it is that you can basically have three main operations during the parsing phase: `eat`, `read` and `match` (with some variations).

If you want a more in-depth explanation of how a parser works, you can refer to [this video](https://www.youtube.com/watch?v=mwvyKGw2CzU) by @tanhauhau where he builds a mini Svelte 4 from scratch, but the gist of it is that you can basically have three main operations during the parsing phase: `eat`, `read` and `match` (with some variations).

I can't watch it as I'm currently on an airplane, but he's got one for Svelte 5 and I wonder if it covers the same stuff and would be better to refer to here: https://youtu.be/4uV27-OMJR8

I'll take a look later but I think it's basically the same (but this one it's at home, with better audio)...anyway we can always update it 😄

benmccann · 2025-08-03T21:10:21Z

DEVELOPER_GUIDE.md

+
+If the parser doesn't enter this `if`, it will check for all the other language constructs using different strategies to read the information that is needed in the AST (an HTML element for example will need the name, the list of arguments, the fragment etc).
+
+If you want to familiarize yourself with the `svelte` AST, you can go [to the playground](https://svelte.dev/playground), write your `svelte` component and open the `AST Output` tab. This will not only show you the AST of the component but also provide you with hover functionality that will highlight each section of the component when you hover over a section of the AST (and vice versa).


Svelte AST instead of svelte AST

DEVELOPER_GUIDE.md

benmccann · 2025-08-03T21:11:37Z

DEVELOPER_GUIDE.md

+
+If the parser doesn't enter this `if`, it will check for all the other language constructs using different strategies to read the information that is needed in the AST (an HTML element for example will need the name, the list of arguments, the fragment etc).
+
+If you want to familiarize yourself with the `svelte` AST, you can go [to the playground](https://svelte.dev/playground), write your `svelte` component and open the `AST Output` tab. This will not only show you the AST of the component but also provide you with hover functionality that will highlight each section of the component when you hover over a section of the AST (and vice versa).


Suggested change

If you want to familiarize yourself with the `svelte` AST, you can go [to the playground](https://svelte.dev/playground), write your `svelte` component and open the `AST Output` tab. This will not only show you the AST of the component but also provide you with hover functionality that will highlight each section of the component when you hover over a section of the AST (and vice versa).

If you want to familiarize yourself with the Svelte AST, you can go [to the playground](https://svelte.dev/playground), write your Svelte component and open the `AST Output` tab. This will not only show you the AST of the component but also provide you with hover functionality that will highlight each section of the component when you hover over a section of the AST (and vice versa).

DEVELOPER_GUIDE.md

Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>

docs: add developer guide

2d0822b

benmccann reviewed Aug 3, 2025

View reviewed changes