docs: add developer guide #16517
docs: add developer guide #16517
Conversation
|
|
|
|
||
| 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). |
There was a problem hiding this comment.
| 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). |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 😄
DEVELOPER_GUIDE.md
Outdated
|
|
||
| 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). |
There was a problem hiding this comment.
Svelte AST instead of svelte AST
DEVELOPER_GUIDE.md
Outdated
|
|
||
| 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). |
There was a problem hiding this comment.
| 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). |
Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>
|
|
||
| Depending on where you read `count` it will refer to a different variable that has been shadowed. The `count` in the template and in `increase` refers to the `count` declared in instance script, while the one in the `log` function will refer to its argument. | ||
|
|
||
| This is done by walking the AST and manually create a `new Scope` class every time we encounter a node that creates one. |
There was a problem hiding this comment.
it's unclear to me if new Scope takes any parameters or what valid scopes can be or how they are represented
There was a problem hiding this comment.
Is it needed in this context? It was more to illustrate how the scope is created (by walking the AST)...I think I go over what "the concept" of a scope is later (a collection of all the variable created and accessed)
| } | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
it might be helpful to include a list of the sorts of things that should occur in the analysis phase. from my limited time working on the compiler, it seems a design decision that comes up is whether to collect some information and make it available for use later in the transform phase or just check it directly in the transform phase. some guidance as to what goes where might be helpful
There was a problem hiding this comment.
That might be a good idea, will add at the beginning of the "phase" (but i also plan to add something else)
Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com>
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
feat:,fix:,chore:, ordocs:.packages/svelte/src, add a changeset (npx changeset).Tests and linting
pnpm testand lint the project withpnpm lint