marko 5.21.9 → 5.21.10
Sign up to get free protection for your applications and to get access to all the features.
- package/docs/compiler.md +138 -85
- package/docs/vite.md +1 -1
- package/package.json +3 -3
package/docs/compiler.md
CHANGED
|
@@ -1,27 +1,46 @@
|
|
|
1
1
|
# Compiler
|
|
2
2
|
|
|
3
|
-
> **
|
|
4
|
-
> The compiler
|
|
3
|
+
> **Warning**:
|
|
4
|
+
> The compiler API and hooks are not terribly stable. They’re intended for advanced integrations or userland experimentation with new language features.
|
|
5
|
+
>
|
|
6
|
+
> Prefer existing official plugins and the standard tag library when possible.
|
|
5
7
|
|
|
6
8
|
## Compile API
|
|
7
9
|
|
|
10
|
+
> **Warning**:
|
|
11
|
+
> The Compile API is intended for advanced integration with build tools, like Webpack and Rollup. Unless you’re doing that, you probably instead want [`build`/`serve` in the Marko CLI](https://github.com/marko-js/cli#readme), or one of [Marko’s bundler integrations](https://markojs.com/docs/bundler-integrations-overview/).
|
|
12
|
+
|
|
8
13
|
### Compile Functions
|
|
9
14
|
|
|
10
|
-
|
|
15
|
+
Compile functions take two arguments:
|
|
16
|
+
|
|
17
|
+
1. A source Marko template
|
|
18
|
+
2. [`CompileOptions`](#options)
|
|
19
|
+
|
|
20
|
+
Then, they return a `CompileResult`:
|
|
11
21
|
|
|
12
22
|
```ts
|
|
13
23
|
type CompileResult = {
|
|
14
|
-
|
|
15
|
-
map?: SourceMap;
|
|
16
|
-
|
|
24
|
+
code: string;
|
|
25
|
+
map?: SourceMap;
|
|
26
|
+
meta: Record<string, unknown>;
|
|
17
27
|
};
|
|
18
28
|
```
|
|
19
29
|
|
|
20
|
-
|
|
30
|
+
- `code`: The compiled output of executable JavaScript code.
|
|
31
|
+
- `map`: [A source map, used for debugging.](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html)
|
|
32
|
+
- `meta`: Metadata gathered while compiling — nothing terribly useful, probably going to get deprecated.
|
|
33
|
+
- Data about child dependencies. Was useful back when it was primarily the bundlers that handled tree-shaking out server components. Now that happens in the compiler, so we don’t use this anymore and therefore might become inaccurate in the future.
|
|
34
|
+
- A list of `watchFiles`: files that were used to compile the template (e.g. `marko.json`). Used to tell bundlers which files should be watched in dev mode.
|
|
21
35
|
|
|
22
|
-
#### `
|
|
36
|
+
#### `compileFile()` and `compileFileSync`
|
|
23
37
|
|
|
24
|
-
|
|
38
|
+
```ts
|
|
39
|
+
compiler.compileFile(filename: string, options?: CompileOptions): Promise<CompileResult>
|
|
40
|
+
compiler.compileFileSync(filename: string, options?: CompileOptions): CompileResult
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`compileFile` and `compileFileSync` load `filename` from disk to use as a source template, then translate it into JavaScript.
|
|
25
44
|
|
|
26
45
|
```js
|
|
27
46
|
import * as compiler from "@marko/compiler";
|
|
@@ -34,11 +53,16 @@ const syncResult = compiler.compileFileSync("./src/index.marko", {
|
|
|
34
53
|
});
|
|
35
54
|
```
|
|
36
55
|
|
|
37
|
-
#### `
|
|
56
|
+
#### `compile()` and `compileSync()`
|
|
38
57
|
|
|
39
|
-
|
|
58
|
+
```ts
|
|
59
|
+
compiler.compile(src: string, filename: string, options?: CompileOptions): Promise<CompileResult>
|
|
60
|
+
compiler.compileSync(src: string, filename: string, options?: CompileOptions): CompileResult
|
|
61
|
+
```
|
|
40
62
|
|
|
41
|
-
`compile` and `compileSync`
|
|
63
|
+
`compile` and `compileSync` accept source templates as a string, rather than loading from disk.
|
|
64
|
+
|
|
65
|
+
The `filename` location is used for resolving taglibs and imports, but does not have to be an actually existing file. <!-- TODO: should it be renamed to baseFile or importBase or something? -->
|
|
42
66
|
|
|
43
67
|
```js
|
|
44
68
|
import * as compiler from "@marko/compiler";
|
|
@@ -55,64 +79,79 @@ const syncResult = compiler.compileSync("<h1>Hello!</>", "./src/index.marko", {
|
|
|
55
79
|
|
|
56
80
|
### Options
|
|
57
81
|
|
|
58
|
-
|
|
82
|
+
The compiler may be configured globally to change its default options:
|
|
59
83
|
|
|
60
84
|
```js
|
|
61
85
|
import * as compiler from "@marko/compiler";
|
|
62
86
|
compiler.configure({ output: "dom" });
|
|
63
87
|
```
|
|
64
88
|
|
|
89
|
+
Or you can pass options objects when calling compile functions. Each property will override individual properties set by `configure()`:
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
import * as compiler from "@marko/compiler";
|
|
93
|
+
compiler.configure({
|
|
94
|
+
output: "dom",
|
|
95
|
+
sourceMaps: true
|
|
96
|
+
});
|
|
97
|
+
const result = compiler.compileFileSync("./example.marko", {
|
|
98
|
+
output: "html"
|
|
99
|
+
});
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
In the above example, `result` would be compiled with the options of `{ output: "html", sourceMaps: true }`.
|
|
103
|
+
|
|
65
104
|
#### `output`
|
|
66
105
|
|
|
67
106
|
Type: `string`<br>
|
|
68
107
|
Default: `"html"`
|
|
69
108
|
|
|
70
|
-
- `"html"
|
|
71
|
-
- `"dom"
|
|
72
|
-
- `"hydrate"
|
|
73
|
-
- `"migrate"
|
|
74
|
-
- `"source"
|
|
109
|
+
- `"html"`: compiles templates to JavaScript that generates HTML strings for server HTTP responses, writing `.html` files, or maybe even constructing `Response`s in Web Workers.
|
|
110
|
+
- `"dom"`: compiles templates to JavaScript that generates DOM nodes for client-side rendering in browsers.
|
|
111
|
+
- `"hydrate"`: like `"dom"`, but only includes assets & components needed in-browser, assuming the page was rendered on the server.
|
|
112
|
+
- `"migrate"`: only runs migrations (no transforms or translation) and returns the migrated template code.
|
|
113
|
+
- `"source"`: parses templates without running any migrations or transforms. (Useful with `ast: true`)
|
|
75
114
|
|
|
76
|
-
|
|
115
|
+
> **Note**:
|
|
116
|
+
> For `dom` or `hydrate` outputs, you should also specify a [`resolveVirtualDependency`](#resolvevirtualdependency) function.
|
|
77
117
|
|
|
78
118
|
#### `code`
|
|
79
119
|
|
|
80
120
|
Type: `boolean`<br>
|
|
81
|
-
Default: true
|
|
121
|
+
Default: `true`
|
|
82
122
|
|
|
83
|
-
If
|
|
123
|
+
If `false`, will not generate or return the compiled `code` string.
|
|
84
124
|
|
|
85
125
|
#### `ast`
|
|
86
126
|
|
|
87
127
|
Type: `boolean`<br>
|
|
88
|
-
Default: false
|
|
128
|
+
Default: `false`
|
|
89
129
|
|
|
90
|
-
|
|
130
|
+
If `true`, the compiler will provide the `ast` in its output.
|
|
91
131
|
|
|
92
132
|
#### `stripTypes`
|
|
93
133
|
|
|
94
134
|
Type: `boolean|undefined`<br>
|
|
95
|
-
Default: undefined
|
|
135
|
+
Default: `undefined`
|
|
96
136
|
|
|
97
|
-
|
|
98
|
-
If the value is `undefined
|
|
99
|
-
the `output` option is not `source` or `migrate`.
|
|
137
|
+
If `true`, removes all TypeScript types from the output.
|
|
138
|
+
If the value is `undefined` (the default), the compiler will remove types if the `output` option is not `source` or `migrate`.
|
|
100
139
|
|
|
101
|
-
For example to run migrations _and_ strip types you can set both `output: "migrate"` and `stripTypes: true`.
|
|
140
|
+
For example, to run migrations _and_ strip types, you can set both `output: "migrate"` and `stripTypes: true`.
|
|
102
141
|
|
|
103
142
|
#### `runtimeId`
|
|
104
143
|
|
|
105
144
|
Type: `string`<br>
|
|
106
|
-
Default: undefined
|
|
145
|
+
Default: `undefined`
|
|
107
146
|
|
|
108
|
-
Optionally use to override the runtime
|
|
147
|
+
Optionally use to override the runtime ID used to differentiate multiple copies of Marko on the same page, which is passed to `marko/components.init(runtimeId)` when compiling in the `hydrate` output.
|
|
109
148
|
|
|
110
149
|
#### `writeVersionComment`
|
|
111
150
|
|
|
112
151
|
Type: `boolean`<br>
|
|
113
152
|
Default: `true`
|
|
114
153
|
|
|
115
|
-
Whether the version should be written to the template
|
|
154
|
+
Whether the Marko version should be written to the template in a comment, like so:
|
|
116
155
|
|
|
117
156
|
```js
|
|
118
157
|
// Compiled using marko@x.x.x - DO NOT EDIT
|
|
@@ -123,7 +162,10 @@ Whether the version should be written to the template as a comment e.g.
|
|
|
123
162
|
Type: `boolean`<br>
|
|
124
163
|
Default: `false`
|
|
125
164
|
|
|
126
|
-
Whether unrecognized tags should be silently ignored
|
|
165
|
+
Whether unrecognized tags should be silently ignored or throw a compile error. Ignored tags will be output as native elements.
|
|
166
|
+
|
|
167
|
+
> **ProTip**:
|
|
168
|
+
> Some test setups use this alongside `@marko/compiler/taglib`'s `excludeDir` and `excludePackage` to simulate "shallow" rendering.
|
|
127
169
|
|
|
128
170
|
#### `sourceMaps`
|
|
129
171
|
|
|
@@ -155,14 +197,14 @@ Use a different file system object (eg. webpack's [CachedInputFileSystem](https:
|
|
|
155
197
|
Type: `string` (`"esm"` or `"cjs"`)<br>
|
|
156
198
|
Default: `"esm"`
|
|
157
199
|
|
|
158
|
-
By default Marko outputs ES Modules
|
|
200
|
+
By default Marko outputs ES Modules. You can optionally specify `"cjs"` for CommonJS/`require()`.
|
|
159
201
|
|
|
160
202
|
#### `optimize`
|
|
161
203
|
|
|
162
204
|
Type: `boolean`<br>
|
|
163
205
|
Default: [environment based](https://github.com/marko-js/marko/blob/0f212897d2d3ec30b12c2f18ba950818bccb83b4/packages/compiler/src/babel-plugin/index.js#L277-L284) (`false` in development, `true` in production)
|
|
164
206
|
|
|
165
|
-
Enables production mode optimizations
|
|
207
|
+
Enables production mode optimizations.
|
|
166
208
|
|
|
167
209
|
#### `resolveVirtualDependency`
|
|
168
210
|
|
|
@@ -181,7 +223,7 @@ Type:
|
|
|
181
223
|
|
|
182
224
|
Default: `undefined`
|
|
183
225
|
|
|
184
|
-
This option should be set
|
|
226
|
+
This option should be set for `dom` or `hydrate` outputs. Since Marko templates can represent multiple output files (eg. JS renderer and CSS styles), a single source `.marko` file must be treated as potentially multiple virtual files.
|
|
185
227
|
|
|
186
228
|
Different build tools have different mechanisms for handling virtual files. You should pass a function that returns a virtual path that can be handled by your build tool.
|
|
187
229
|
|
|
@@ -194,8 +236,7 @@ const virtualSources = new Map();
|
|
|
194
236
|
function resolveVirtualDependency(filename, { virtualPath, code, map }) {
|
|
195
237
|
const virtualFilename = `${filename}?virtual=${virtualPath}`;
|
|
196
238
|
|
|
197
|
-
// Add
|
|
198
|
-
// to be later accessed by the loader
|
|
239
|
+
// Add virtual source to the lookup to be later accessed by the loader
|
|
199
240
|
virtualSources.set(virtualFilename, { code, map });
|
|
200
241
|
|
|
201
242
|
// Generate the webpack path, from right to left...
|
|
@@ -233,14 +274,14 @@ export default function markoLoader(source) {
|
|
|
233
274
|
|
|
234
275
|
#### `hydrateIncludeImports`
|
|
235
276
|
|
|
236
|
-
This option is only used for `output: "hydrate"`. By default
|
|
277
|
+
This option is only used for `output: "hydrate"`. By default, `import`s in server-only files are not included in the hydrate output. However, for some assets, like stylesheets, it is useful to have them included in hydrate mode.
|
|
237
278
|
|
|
238
279
|
The `hydrateIncludeImports` option allows you to provide a function which receives an import path, or a regexp to match against that path which tells Marko to include that import in the hydrate mode output.
|
|
239
280
|
|
|
240
|
-
The default regexp includes a list of common known asset file extensions and is as follows:
|
|
281
|
+
The default regexp includes a list of common known asset file extensions, and is as follows:
|
|
241
282
|
|
|
242
283
|
```js
|
|
243
|
-
/\.(css|less|s[ac]ss|styl|png|jpe?g|gif|svg|ico|webp|avif|mp4|webm|ogg|mp3|wav|flac|aac|woff2?|eot|
|
|
284
|
+
/\.(css|less|s[ac]ss|styl|png|jpe?g|gif|svg|ico|webp|avif|mp4|webm|ogg|mp3|wav|flac|aac|woff2?|eot|[ot]tf)$/;
|
|
244
285
|
```
|
|
245
286
|
|
|
246
287
|
Looking at a partial Marko file such as:
|
|
@@ -253,19 +294,16 @@ import "./baz.wasm";
|
|
|
253
294
|
<div/>
|
|
254
295
|
```
|
|
255
296
|
|
|
256
|
-
|
|
297
|
+
For `hydrate` output, with the default `hydrateIncludeImports`, would only cause `./foo.css` to be loaded in the browser.
|
|
257
298
|
|
|
258
299
|
#### `cache`
|
|
259
300
|
|
|
260
|
-
Type: typeof [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) (specifically,
|
|
301
|
+
Type: typeof [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) (specifically, `.get()` is required)<br>
|
|
261
302
|
Default: `new Map()`
|
|
262
303
|
|
|
263
|
-
Compiling a Marko template may require other (used) Marko templates to compile.
|
|
264
|
-
To prevent compiling templates more than once, most of the compilation is cached.
|
|
304
|
+
Compiling a Marko template may require other (used) Marko templates to compile. To prevent compiling templates more than once, most of the compilation is cached.
|
|
265
305
|
|
|
266
|
-
The default cache strategy is to clear the cache
|
|
267
|
-
If the default cache is overwritten it is up to the user to determine when the
|
|
268
|
-
cache is cleared.
|
|
306
|
+
The default cache strategy is to clear the cache each macrotask. If the default cache is overwritten, it is up to the user to determine when the cache is cleared.
|
|
269
307
|
|
|
270
308
|
#### `babelConfig`
|
|
271
309
|
|
|
@@ -285,22 +323,29 @@ Default: babel defaults, plus
|
|
|
285
323
|
Type: `{ analyze: Visitor, transform:Visitor }`<br>
|
|
286
324
|
Default: [autodiscovers](https://github.com/marko-js/marko/blob/0f212897d2d3ec30b12c2f18ba950818bccb83b4/packages/compiler/src/config.js#L46-L89) a translator package starting with `@marko/translator-` or `marko-translator-`
|
|
287
325
|
|
|
288
|
-
The translator is a collection of transforms that translates the Marko AST into a valid JavaScript AST based on the `output` option. There is a default translator
|
|
326
|
+
The translator is a collection of transforms that translates the Marko AST into a valid JavaScript AST based on the `output` option. There is a default translator in Marko, but this option may be used to switch to experimental translators for alternate runtimes.
|
|
289
327
|
|
|
290
|
-
The translator is an object with
|
|
328
|
+
The translator is an object with `analyze` and `transform` [Babel Visitors](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#visitors):
|
|
329
|
+
|
|
330
|
+
- The result of the `analyze` visitor is cached and may be requested by other templates.
|
|
331
|
+
- The `transform` visitor transforms the AST to its final JavaScript AST.
|
|
291
332
|
|
|
292
333
|
See [`@marko/translator-default`](https://github.com/marko-js/marko/blob/11a10f82cdb5389880e6deca5f77d17727acb831/packages/translator-default/src/index.js) for a reference implementation.
|
|
293
334
|
|
|
294
335
|
## Hooks
|
|
295
336
|
|
|
296
|
-
|
|
337
|
+
> **Note**:
|
|
338
|
+
> These compiler hooks aren’t terribly stable either. Using hooks for one-time migrations, like a codemod, is the best-supported way to use the compiler hooks, since you won’t have to worry about the code changing underneath you in the future.
|
|
339
|
+
|
|
340
|
+
|
|
297
341
|
|
|
298
|
-
The Marko compiler runs
|
|
299
|
-
These stages are intended for different aspects of processing the template and can be hooked into using [`marko.json`](./marko-json.md) configuration.
|
|
342
|
+
The Marko compiler runs a series of stages to produce its final JavaScript output. These stages handle different steps of template processing, and can be tweaked, extended, and hooked into with [`marko.json` configuration files](./marko-json.md).
|
|
300
343
|
|
|
301
|
-
All compiler hooks must export a visitor which will receive a [babel NodePath](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#paths) with a `MarkoTag` node.
|
|
344
|
+
- All compiler hooks must have a default export of a [Babel-style visitor function](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#toc-visitors), which will receive a [babel `NodePath`](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#paths) with a `MarkoTag` node.
|
|
302
345
|
|
|
303
|
-
|
|
346
|
+
- Hooks will also receive a `types` object that matches the [`@babel/types`](https://babeljs.io/docs/en/babel-types) API extended with the [Marko AST types](#marko-ast). (You may also reference the types by importing `{ types } from "@marko/compiler"`.)
|
|
347
|
+
|
|
348
|
+
- Hooks may alternatively export an `enter` function (alias of `default`), and optionally an `exit` function. These map to [`@babel/traverse`’s `enter` and `exit` methods](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#babel-traverse).
|
|
304
349
|
|
|
305
350
|
Here is an example hook:
|
|
306
351
|
|
|
@@ -313,18 +358,15 @@ export default (tag, types) => {
|
|
|
313
358
|
};
|
|
314
359
|
```
|
|
315
360
|
|
|
316
|
-
Hooks can also export an `enter` (alias of `default`) and an `exit` function. These map to [@babel/traverse's](https://github.com/jamiebuilds/babel-handbook/blob/master/translations/en/plugin-handbook.md#babel-traverse) `enter` and `exit` methods.
|
|
317
|
-
|
|
318
361
|
### Parse
|
|
319
362
|
|
|
320
|
-
|
|
321
|
-
If you've not heard the term before, put simply it is just an object representation of your code.
|
|
363
|
+
Marko compilation starts by converting the raw text of your Marko template into an [AST (Abstract Syntax Tree)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) — an object representation of your code.
|
|
322
364
|
|
|
323
365
|
```marko
|
|
324
366
|
<h1>Hello!</h1>
|
|
325
367
|
```
|
|
326
368
|
|
|
327
|
-
|
|
369
|
+
…will roughly become:
|
|
328
370
|
|
|
329
371
|
```json
|
|
330
372
|
{
|
|
@@ -345,63 +387,74 @@ Will roughly become
|
|
|
345
387
|
}
|
|
346
388
|
```
|
|
347
389
|
|
|
348
|
-
This might look a bit verbose, but
|
|
390
|
+
This might look a bit verbose, but ASTs aim for completeness, not terseness.
|
|
391
|
+
|
|
392
|
+
Marko parses in two steps to stay flexible with the ever-changing syntax of JavaScript:
|
|
393
|
+
|
|
394
|
+
1. The first parsing pass happens in our [`htmljs-parser`](https://github.com/marko-js/htmljs-parser), which understands the HTML and HTML-like parts of your template.
|
|
349
395
|
|
|
350
|
-
|
|
351
|
-
The first pass of parsing happens in our very own [htmljs-parser](https://github.com/marko-js/htmljs-parser), which understands the HTML parts of your template.
|
|
396
|
+
2. For JavaScript expressions, Marko defers to [`@babel/parser`](https://babeljs.io/docs/en/babel-parser). The resulting [Marko AST](#marko-ast) is a superset of what `@babel/parser` would return.
|
|
352
397
|
|
|
353
|
-
|
|
398
|
+
To hook into the `parse` stage, use [the `parse` option in the `marko.json` file](https://markojs.com/docs/marko-json/#paths).
|
|
354
399
|
|
|
355
|
-
|
|
356
|
-
|
|
400
|
+
> **Note**: The `parse` hook deviates from the other compiler hooks:
|
|
401
|
+
>
|
|
402
|
+
> - It does not support the `enter` & `exit` API.
|
|
403
|
+
> - You _must return_ a replacement AST node.
|
|
357
404
|
|
|
358
405
|
### Migrate
|
|
359
406
|
|
|
360
|
-
That
|
|
361
|
-
These migrations run automatically in the background and can be written to disk when users are ready by running the [`@marko/migrate` CLI command](https://github.com/marko-js/cli/blob/master/packages/migrate/README.md).
|
|
407
|
+
That’s right, Marko has _first-class_ support for migrations. The **migration stage** can translate outdated APIs into modern counterparts, leaving the rest of the compilation none the wiser.
|
|
362
408
|
|
|
363
|
-
|
|
409
|
+
Migrations run automatically in the background, and can be written to disk when users are ready by running the [`@marko/migrate` CLI command](https://github.com/marko-js/cli/blob/master/packages/migrate/README.md).
|
|
410
|
+
|
|
411
|
+
To hook into the `migrate` stage, [use the `migrate` option in the `marko.json` file](https://markojs.com/docs/marko-json/#paths).
|
|
364
412
|
|
|
365
413
|
> **Note:**
|
|
366
|
-
> To make the compiler
|
|
414
|
+
> To make the compiler stop at this point and output the migrated template, rather than continuing to produce the JavaScript output, [set `output: "migrate"`](#output) in the [compilation options](#options).
|
|
367
415
|
|
|
368
416
|
### Transform
|
|
369
417
|
|
|
370
|
-
The transform stage
|
|
418
|
+
The **transform stage** is meant for userland transformations of Marko code into different Marko code. Think of it like [`babel.transform`](https://babeljs.io/docs/en/babel-core#transform) for Marko templates.
|
|
371
419
|
At this stage, you are given a fully parsed and migrated AST to do what you will with.
|
|
372
420
|
|
|
373
|
-
To hook into the `transform` stage
|
|
421
|
+
To hook into the `transform` stage, [use the `transform` option in the `marko.json` file](https://markojs.com/docs/marko-json/#paths).
|
|
374
422
|
|
|
375
423
|
### Analyze
|
|
376
424
|
|
|
377
|
-
Next
|
|
378
|
-
|
|
425
|
+
Next is the **analyze stage**, intended for non-mutative analysis of the entire AST in a way that can be cached in RAM.
|
|
426
|
+
|
|
427
|
+
> **Note**:
|
|
428
|
+
> “Non-mutative analysis” means that if you modify the AST during this stage, _you’ll probably regret it_ someday.
|
|
379
429
|
|
|
380
|
-
|
|
430
|
+
Metadata should be stored on nodes’ `.extra` property. These `.extra` properties are typically read in [the translate stage](#translate), or when using the child template analysis helpers.
|
|
431
|
+
|
|
432
|
+
To hook into the `analyze` stage, [use the `analyze` option in the `marko.json` file](https://markojs.com/docs/marko-json/#paths).
|
|
381
433
|
|
|
382
434
|
### Translate
|
|
383
435
|
|
|
384
|
-
Finally, we have the translation stage
|
|
436
|
+
Finally, we have the **translation stage**. This stage is Marko’s “Rosetta Stone”, and is responsible for turning your beautiful `.marko` code into different versions of optimized JavaScript you’d rather not write yourself.
|
|
385
437
|
|
|
386
|
-
To hook into the `translate` stage
|
|
438
|
+
To hook into the `translate` stage, [use the `translate` option in the `marko.json` file](https://markojs.com/docs/marko-json/#paths).
|
|
387
439
|
|
|
388
440
|
## Utilities
|
|
389
441
|
|
|
390
|
-
The
|
|
442
|
+
[The `@marko/babel-utils` package](https://github.com/marko-js/marko/tree/master/packages/babel-utils/index.d.ts) exposes a handful of utilities for various tasks on [Marko ASTs](#marko-ast).
|
|
443
|
+
|
|
444
|
+
### Marko AST
|
|
391
445
|
|
|
392
|
-
|
|
446
|
+
Marko extends Babel’s AST types to add nodes for `MarkoTag`, `MarkoAttribute`, etc.
|
|
393
447
|
|
|
394
|
-
|
|
395
|
-
For AST creation and assertion utilities you can import Marko's superset of `@babel/types` through the compiler:
|
|
448
|
+
For AST creation and assertion utilities, you can import Marko’s `@babel/types` superset from the compiler package:
|
|
396
449
|
|
|
397
450
|
```js
|
|
398
451
|
import { types } from "@marko/compiler";
|
|
399
452
|
```
|
|
400
453
|
|
|
401
|
-
The [`@babel/types` documentation](https://babeljs.io/docs/en/babel-types) shows all
|
|
454
|
+
The [`@babel/types` documentation](https://babeljs.io/docs/en/babel-types) shows all utility methods available for Babel AST nodes. When importing `types` from `@marko/compiler`, you also get the same types of utilities for Marko nodes: `types.markoTag`, `types.isMarkoTag`, `types.assertMarkoTag`, and so on.
|
|
402
455
|
|
|
403
|
-
For
|
|
456
|
+
For full definitions, view the source code for Babel and Marko:
|
|
404
457
|
|
|
405
|
-
- [Babel
|
|
406
|
-
- [Babel
|
|
407
|
-
- [Marko
|
|
458
|
+
- [Babel’s Core Definitions](https://github.com/babel/babel/blob/master/packages/babel-types/src/definitions/core.js)
|
|
459
|
+
- [Babel’s Extended Definitions](https://github.com/babel/babel/tree/master/packages/babel-types/src/definitions)
|
|
460
|
+
- [Marko’s Definitions](https://github.com/marko-js/marko/blob/master/packages/compiler/src/babel-types/types/definitions.js)
|
package/docs/vite.md
CHANGED
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "marko",
|
|
3
|
-
"version": "5.21.
|
|
3
|
+
"version": "5.21.10",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"description": "UI Components + streaming, async, high performance, HTML templating for Node.js and the browser.",
|
|
6
6
|
"dependencies": {
|
|
7
|
-
"@marko/compiler": "^5.22.
|
|
8
|
-
"@marko/translator-default": "^5.21.
|
|
7
|
+
"@marko/compiler": "^5.22.9",
|
|
8
|
+
"@marko/translator-default": "^5.21.7",
|
|
9
9
|
"app-module-path": "^2.2.0",
|
|
10
10
|
"argly": "^1.2.0",
|
|
11
11
|
"browser-refresh-client": "1.1.4",
|