> This is the Markdown rendition of https://pyxle.dev/docs/advanced/compiler-internals, served for AI agents and assistants. > Append `.md` to any pyxle.dev URL to fetch its Markdown; the links below already do. > Index of every page: https://pyxle.dev/llms.txt · Whole docs in one file: https://pyxle.dev/llms-full.txt > Search the docs: https://pyxle.dev/api/docs-search?q=YOUR+QUERY (returns matching pages as Markdown links) # Compiler Internals The Pyxle compiler transforms `.pyxl` files into separate Python and JSX artifacts. This document explains how the compilation process works. ## Compilation overview When you run `pyxle dev` or `pyxle build`, the compiler: 1. Scans the `pages/` directory for `.pyxl` files 2. Parses each file to separate Python from JSX 3. Writes server-side Python modules to `.pyxle-build/server/` 4. Writes client-side JSX modules to `.pyxle-build/client/` 5. Generates layout composition wrappers in `.pyxle-build/client/routes/` 6. Creates a Vite configuration at `.pyxle-build/vite.config.js` ## The parser The parser (`pyxle/compiler/parser.py`) is **AST-driven** — there are no fence markers, string directives, or per-line keyword heuristics. It finds the Python/JSX boundary by walking the source and, at each position, growing the largest region that parses as valid Python via `ast.parse`; when Python stops parsing, it grows a JSX segment until valid Python resumes. ### How the split works - The boundary is decided by **what parses as Python**, not by the leading keyword. `import React from 'react'` is not valid Python, so it lands in JSX; `from db import users` is, so it stays in Python. - Arbitrary alternation is supported (`python | jsx | python | jsx | ...`), including JSX-first files. - Inside a JSX segment the parser tracks JS structural state (string and template literals, block comments, brace/paren/bracket depth), so Python-looking text inside a JSX body or template literal is never misclassified. ### What the parser extracts | Artifact | Description | |----------|-------------| | `python_code` | All Python lines concatenated | | `jsx_code` | All JSX lines concatenated | | `loader` | `@server` function metadata (name, line number, parameters) | | `actions` | `@action` function metadata (name, line number, parameters) | | `head_elements` | Static `HEAD` variable content | | `head_is_dynamic` | Whether `HEAD` is a callable | | `head_jsx_blocks` | `...` JSX blocks extracted for server-side use | | `script_declarations` | `