The dev server

pyxle dev is the command you'll spend the most time with. It runs a Starlette ASGI app on port 8000, a Vite subprocess on port 5173, an SSR worker pool, an incremental compiler, a file watcher, and a WebSocket error overlay — all coordinated as a single async program.

This doc explains how those pieces fit together. By the end you'll understand what every line in the startup banner means, what happens when you save a file, and how to read the dev server's source code.

Files (pyxle/devserver/):

That's a lot. Most of it doesn't matter for understanding how the dev server works at a high level. The key pieces are: the Starlette app, the builder, the watcher, Vite, and the registry. Everything else is supporting infrastructure around those five.

Lifecycle in one diagram

$ pyxle dev
   │
   ▼
1. Load config
   - Read pyxle.config.json
   - Apply env vars
   - Apply CLI flags
   - Build a frozen DevServerSettings
   │
   ▼
2. Initial compile (builder.py)
   - Scan pages/ for .pyxl and .py files
   - Compile every file via PyxParser + ArtifactWriter
   - Write .pyxle-build/{server,client,metadata}/ artifacts
   - Compose layouts
   - Build the metadata registry → RouteTable
   │
   ▼
3. Start Vite (vite.py)
   - Spawn `vite dev --port 5173`
   - Wait for TCP readiness on port 5173
   - Auto-restart if Vite crashes
   │
   ▼
4. Start the SSR worker pool (ssr/worker_pool.py)
   - Spawn N persistent Node.js workers (default: 1)
   - Each worker speaks NDJSON on stdin/stdout
   │
   ▼
5. Build the Starlette app (starlette_app.py)
   - Register page, API, action routes
   - Add middleware (CORS, CSRF, static, custom, Vite proxy)
   - Add health endpoints (/healthz, /readyz)
   - Add WebSocket route for the overlay
   │
   ▼
6. Start the file watcher (watcher.py)
   - Rebuild watch: pages/, dev.watch dirs, global stylesheets/scripts
   - Index-only watch: public/ (served live — never rebuilds/reloads)
   - Debounce events for 250ms
   - On a rebuild-watch change: rebuild via builder.py and reload registry
   │
   ▼
7. Start uvicorn on port 8000
   - The Starlette app is now serving requests

When all seven steps are done, the console shows a curated startup summary:

✅ Pyxle dev server ready in 512 ms
ℹ️    Local:   http://127.0.0.1:8000
ℹ️    Vite:    http://127.0.0.1:5173
ℹ️    Routes:  13 page(s), 1 API route(s)

By default the per-line Vite firehose and the internal step-by-step lifecycle chatter (Preparing …, Launching Vite …, Discovered … route(s), the raw [vite] … output) are hidden so the console stays readable. Each incremental rebuild then prints a single concise line (✅ Rebuilt … in X ms). Run pyxle dev --verbose (or pyxle -v dev) to restore the full firehose and the debug-level internals — every one of those hidden lines is emitted at debug level, so verbose mode surfaces the entire lifecycle for troubleshooting.

Genuine signal — errors, warnings, the URLs, and rebuild success/failure — is always shown regardless of verbosity.

The Starlette app

create_starlette_app() (devserver/starlette_app.py:506) is the factory function that builds the entire ASGI application. It returns a Starlette instance with:

Routes

• Page routes (build_page_router(), line 291) — one Starlette Route per PageRoute in the route table. Each route has a closure handler that knows which page to render.
• API routes (build_api_router(), line 187) — one Starlette endpoint per pages/api/*.py file. Functions named after HTTP methods (get, post, etc.) get registered for those methods; a function named handle gets all methods.
• Action routes (build_action_router(), line 363) — POST-only endpoints under /api/__actions/{name} for every @action decorated function.
• Static asset mount (build_client_assets_mount(), line 498) — serves /client/* and /dist/* directly from disk.
• Public files mount (build_static_files_mount(), line 485) — serves whatever's in public/.
• Health endpoints — /healthz and /readyz for orchestration.
• Catch-all 404 — walks up the request path looking for the nearest not-found.pyxl boundary.
• WebSocket route at /__pyxle__/overlay — used by the dev overlay client.

Middleware stack

Listed from outermost to innermost (outermost runs first on request, last on response):

1. GZip — production only
2. CORS — if cors is configured in pyxle.config.json
3. CSRF — if csrf.enabled is true in config
4. StaticAssetsMiddleware — short-circuits requests for /client/* and public assets so they don't reach the page router
5. Custom user middleware — anything declared in pyxle.config.json middleware: ["mymodule:MyMiddleware"]
6. Vite proxy — dev only, forwards JS/CSS/HMR requests to Vite

The middleware stack is built in create_starlette_app() line ~668. Each middleware is added with Middleware(...) and Starlette chains them in order.

Lifespan hooks

Starlette has a lifespan callback that runs on startup and shutdown. Pyxle uses it to:

• Start the SSR worker pool on startup
• Stop the worker pool gracefully on shutdown (give workers 5 seconds to exit cleanly, then kill any holdouts)

This means workers are alive for the lifetime of the dev server, not per-request.

The incremental builder

build_once() (devserver/builder.py:50) is the function that runs one build pass — initial compile, or rebuild after a file change. It:

1. Scans pages/ with scanner.scan_source_tree() to find every .pyxl, pages/api/*.py, and client asset file. For each file, it computes the SHA256 hash of the contents.
2. Compares hashes against the previous build's metadata to find which files actually changed since last time.
3. Compiles only the changed .pyxl files by calling compile_file() for each. Unchanged files are left alone.
4. Copies API modules (pages/api/*.py) to their build location.
5. Composes layouts for any pages whose ancestor layout.pyxl files have changed (layouts.compose_layout_templates()).
6. Syncs global stylesheets and scripts declared in the config.
7. Removes orphaned artifacts for source files that have been deleted since the last build.
8. Returns a BuildSummary dataclass with counts: pages compiled, APIs copied, etc.

The hash-based diffing is the key to performance. A typical 50-page project has thousands of unchanged files at any moment; running the parser on every one of them on every save would be wasteful. With hash diffing, a single-file edit triggers exactly one compile_file() call.

Source: devserver/builder.py:50-160.

When does a layout-only change trigger a page rebuild?

Layouts are tricky: when you edit pages/dashboard/layout.pyxl, every page under pages/dashboard/ needs its composed route module regenerated. The composed module is what bundles the layout with the page, so it needs to be re-emitted whenever the layout's identity changes.

The builder handles this by recompiling layouts first, then re-running the layout composition pass for any page whose ancestor layout was rebuilt. This is invisible to you — you save the layout, and a moment later the affected pages reload in the browser.

The watcher

ProjectWatcher (devserver/watcher.py:101) wraps Python's watchdog library to observe filesystem events. It's structured as:

1. A watchdog observer running in a background thread, posting raw events to a queue.
2. A debounce buffer that aggregates events for 250ms (the default; configurable). Saving a file twice in quick succession only triggers one rebuild.
3. A dispatch callback that the dev server registers; the watcher calls it with the set of changed paths after the debounce window expires.

The dispatch callback runs build_once() and then refreshes the metadata registry. If the build fails (e.g., a parser error), the watcher captures the exception and broadcasts it to the WebSocket overlay so the browser can display the error inline.

Module cache invalidation

When a .pyxl file's Python half changes, the dev server's existing imported version of the compiled .py is stale. Python's import system caches modules in sys.modules — re-importing the same module key returns the cached version.

So that module-level globals persist across requests exactly like pyxle serve, the dev server imports a page/action module once and reuses it, re-importing only after a rebuild. A rebuild advances a process-wide reload generation (ssr/module_cache.py); each imported module is stamped with the generation it was built against, and the importer re-imports from disk when the generation has advanced. Changed .py helper modules are additionally dropped from sys.modules (_invalidate_python_modules), so a re-imported page picks up an edited helper too.

This is why Python edits show up immediately without restarting the dev server. The hot-reload story is: write file → watcher fires → incremental build → reload generation advances → next request re-imports the new code (module-level state resets, as it would on any restart). Between rebuilds the module is reused, so a module-level counter or cache persists across requests — but only per process (see SSR → module reuse).

What's watched

By default, the watcher observes:

• pages/ — recursive, on the rebuild watch (a change runs build_once() and reloads the browser)
• Any directory listed in dev.watch — also on the rebuild watch, so a shared Python module imported from outside pages/ (e.g. lib/) hot-reloads
• Any file referenced in globalStyles or globalScripts config
• public/ — recursive, but on a lightweight index-only watch that never rebuilds or reloads (see below)
• The pyxle.config.json itself (changing the config triggers a full restart, not a hot-reload)

On the rebuild watch, generated build output is ignored so a rebuild's own writes don't trigger another rebuild: .pyxle-build/ and __pycache__/ trees, *.pyc bytecode, and *.db/*.db-wal/*.db-shm journals. A dev.ignore list adds extra glob patterns on top of these built-ins — it can add ignores but never clear them. The watcher does not watch node_modules/ or dist/.

The watcher also reacts only to genuine change events — create, modify, delete, rename, and writable-close — and ignores read-only file open/close events. This matters on Linux: a rebuild reads every source file to hash and recompile it, and those reads surface through inotify as open/close events. Treating a read as an edit would let the rebuild's own reads re-trigger it in an endless loop; filtering to real changes prevents that. (macOS FSEvents never reports reads, so the loop only ever appeared on Linux.)

public/ is served live, not rebuilt

Changes under public/ do not rebuild or reload the page — matching Next.js, which never rebuilds on public/ changes. Public assets are served straight from disk (dev serves them with a revalidating no-cache header), so an edited file is reflected on the next request/refresh with no watcher action.

The watcher still keeps a lightweight watch on public/ for one job: a newly created or deleted file changes which URLs resolve, so those structural events refresh the static-file index the static middleware uses for its O(1) membership check. That's how a freshly added public asset becomes reachable without restarting pyxle dev. This index watch never calls build_once() and never touches the browser-reload channel. (pyxle serve builds the index once and runs no watcher — the production tree is immutable.)

Vite integration

ViteProcess (devserver/vite.py:21) supervises the Vite dev server subprocess. The Vite process is responsible for:

• Bundling JSX for the browser (with React Refresh / HMR)
• Serving static assets from .pyxle-build/client/
• Handling client-side hot module replacement when JSX files change

Pyxle's dev server does not serve JS/CSS to the browser directly. Instead, it proxies asset requests to Vite's port. This sounds inefficient but it isn't: the proxy just forwards bytes, and Vite is the JS expert.

Spawning Vite

ViteProcess tries several command resolutions to find Vite:

1. node_modules/.bin/vite — local install via npm
2. node_modules/vite/bin/vite.js — local install, called via node
3. npx vite — fallback if neither local install exists

Each candidate is validated with --version before being committed to. If Vite isn't installed at all, Pyxle automatically runs npm install to restore dependencies. (This is also why a fresh pyxle init works on the second pyxle dev: the first attempt notices the missing dependencies and installs them.)

Source: devserver/vite.py:225.

Readiness probing

After spawning Vite, Pyxle polls Vite's TCP port (default 5173) every 100ms until it accepts connections. Once it does, Vite is "ready" and Pyxle starts serving page requests. The whole readiness window is usually under a second.

If Vite takes longer than 10 seconds to come up, Pyxle reports a timeout and shuts down — usually a sign that something else is holding port 5173.

Auto-restart

If the Vite subprocess exits unexpectedly (crashes, OOMs, gets killed), Pyxle's monitor coroutine catches the exit and schedules a restart after 0.5 seconds. The restart probes for readiness again and re-attaches to the proxy.

This is invisible during normal use but essential for long dev sessions: it keeps Vite running across edits to its config, plugin errors, and Node version mismatches without requiring you to restart the dev server.

Source: devserver/vite.py:302.

The proxy

ViteProxy (devserver/proxy.py:40) is a small ASGI middleware that forwards specific URLs to Vite. It matches:

• Anything ending in .js, .jsx, .ts, .tsx, .mjs, .css, or .map
• Anything starting with /@vite/ (Vite's internal endpoints)
• /@react-refresh (the HMR endpoint)

For matching requests, it uses httpx.AsyncClient.stream() to forward chunks without buffering, so a 5MB CSS file doesn't get loaded into Pyxle's memory before being sent to the browser. Headers are filtered to drop hop-by-hop fields.

For non-matching requests, the middleware passes through to the next layer (the page/API router).

The metadata registry

MetadataRegistry (devserver/registry.py) is the in-memory map from route paths to PageRoute / ApiRoute / ActionRoute objects.

build_metadata_registry() (line 118) walks .pyxle-build/metadata/ and reads each .json file. For every page, it constructs a PageRoute containing:

• The route path (primary)
• Any alias paths (from optional catch-all routes)
• Paths to the server module, client module, and metadata
• The Python module key for importlib
• Loader name and line number
• Static head metadata
• Action metadata

The dev server then iterates the registry to register Starlette routes. After every rebuild, the registry is rebuilt from scratch — Pyxle never tries to incrementally patch the registry, because the cost of a full rebuild is small (millisecond range for typical projects) and the correctness is much easier to reason about.

Layout head discovery

A layout's <Head> JSX block contributes to every page below it. At registry-build time, find_layout_head_jsx_blocks() walks ancestor directories of each page looking for layout.pyxl (and template.pyxl) metadata, collects their head_jsx_blocks, and attaches the merged list to the page's PageRoute. The SSR pipeline reads this at request time without re-parsing.

Source: devserver/registry.py:337.

The error overlay

OverlayManager (devserver/overlay.py:24) maintains a set of WebSocket connections from browser tabs. When the dev server has something to tell the browser — a build error, a runtime error, a successful rebuild — it broadcasts a JSON message to every connected client.

Event types:

• "error" — sent when a build fails or a runtime error occurs. Includes the error message, stack, and "breadcrumbs" describing which stage of the request pipeline failed (loader, render, head evaluation, etc.).
• "clear" — sent when a previously-failing route succeeds. The client uses this to dismiss any visible error overlay.
• "reload" — sent after a successful rebuild. The client triggers a soft reload of the current page.
• "log" — a server-side logging record forwarded to the browser devtools console (dev only). The payload carries the target console method (info/warn/error/debug), the formatted message, and the originating logger name; the client prints it prefixed [pyxle:server]. A bounded logging.Handler (devserver/log_forwarding.py) is attached to the root logger while the dev server runs and detached on shutdown. It never blocks the event loop, drops records when no client is connected or the send fails, guards against re-entrancy, and throttles bursts. By default only INFO+ from your own loggers is forwarded; --verbose also forwards DEBUG and the framework's internal loggers. To make those records reachable (Python's root logger defaults to WARNING, which drops INFO before any handler sees it), the handler lowers the root logger level to INFO (DEBUG under --verbose) for the lifetime of the dev session and restores the previous level on shutdown. A side effect is that if your app has configured its own root handler (e.g. via logging.basicConfig), your INFO logs also become visible in the terminal during pyxle dev. This is dev-only; pyxle serve never touches your logging configuration.

The browser-side overlay client lives in pyxle/client/ and is included in the default scaffold.

How a request flows through the dev server

Putting everything together, here's what happens when the browser asks for a page in dev mode:

GET /dashboard
   │
   ▼
ASGI app (Starlette)
   │
   ▼
1. Static asset middleware
   "Is /dashboard a file in /client/ or /public/?"
   No → pass through
   │
   ▼
2. CORS / CSRF middleware (if enabled)
   "Is the request allowed?"
   Yes → pass through
   │
   ▼
3. Custom user middleware (if any)
   "Anything to do here?"
   No → pass through
   │
   ▼
4. Vite proxy
   "Does /dashboard look like a Vite asset?"
   No → pass through
   │
   ▼
5. Page router
   "Is /dashboard in the route table?"
   Yes → invoke the page handler closure
   │
   ▼
6. Page handler
   - Look up the PageRoute
   - In dev mode, purge stale modules from sys.modules
   - Call the SSR pipeline (build_page_response)
   │
   ▼
7. SSR pipeline (see ssr.md)
   - Run loader
   - Resolve head
   - Render component on a worker
   - Assemble document
   - Stream response
   │
   ▼
HTML response → browser

The browser then loads /client/... URLs for the JS bundle, which hit the static asset middleware and get forwarded to Vite via the proxy. Vite serves them, and React hydrates.

What the dev server is *not*

Let me list a few things the dev server explicitly does not do, because the absences are part of the design:

• It doesn't bundle JS itself. Vite does. Pyxle is a Python framework that proxies a JavaScript bundler — it doesn't try to out-Vite Vite.
• It doesn't watch your node_modules/. Adding a dependency requires pip install (Python) or npm install (JS) followed by a manual pyxle dev restart. We could watch them, but it would triple the watcher's event volume for marginal value.
• It doesn't have its own caching layer. The render cache lives inside the SSR worker (esbuild caches its bundles). The metadata cache is the registry. There's no application-level cache.
• It doesn't guess about routes. Every route comes from a real file on disk. There is no routes.py or urls.py you can manipulate at runtime.
• It doesn't have a "production mode" toggle in dev. pyxle dev is dev. pyxle serve is production. They are different commands for different lifecycles, and trying to make one mode mimic the other usually papers over real differences.

These absences are deliberate. The dev server is meant to be small enough that you can read it cover to cover in an afternoon and understand exactly what it does.

Where to read next

• Server-side rendering — What happens inside a page handler: loader execution, head merging, component rendering on a worker, document assembly, streaming, and client-side navigation.

• Build and serve — How pyxle build takes the same compiled artifacts that pyxle dev produces and packages them for production, and how pyxle serve runs without Vite or the file watcher.

• The CLI — How pyxle dev parses its flags and config and bridges them to DevServerSettings.