Parsing

Five short essays, part 1 of 5.

A compile-to-JS framework typically has to parse a custom file format -- Svelte's

.svelte

single-file components are their own small language, with a parser, a validator and an AST all of its own before any JavaScript is generated.

ARKlight's entry file is plain Python. It still has a parser, but that parser is

ast.parse

from the standard library, pointed only at the entry file's own source, before any of your code runs. It looks for specific *syntax shapes* --

Site()

@site.page("/...")

-- not for what your code does when called.

This is the single fact that explains the two most common build failures:

site.page("/")(home)

is valid Python that does the same thing as the decorator at runtime, but the static scan never executes anything, so it never sees it. And a

@site.page(...)

decorator inside an *imported* module is invisible to a scan that only reads the entry file.

What this buys back

No risk of an entry file with a route registered by a conditional, a loop, or a function call the compiler would have to actually run to find.
A build fails at the same, predictable moment every time, rather than depending on what a dynamic script decided to do this run.
arklight search <Name> can describe the whole component vocabulary up front, because the vocabulary isn't extensible at parse time the way a template language's custom directives can be.

The cost is symmetry: the entry file is the one place route decorators are allowed to live. See

for the exact error each mistake produces.

One pass, a closed vocabulary, no plugin pipeline.

Static HTML/CSS/JS out; no hydration step at all.

State lives on the page, not in an importable store.

Every example here is a file that actually builds.