Configuration Reference

Pyxle is configured via pyxle.config.json in the project root. All fields are optional -- sensible defaults are used when omitted.

Full schema

{
  "pagesDir": "pages",
  "publicDir": "public",
  "buildDir": ".pyxle-build",
  "debug": true,
  "starlette": {
    "host": "127.0.0.1",
    "port": 8000
  },
  "vite": {
    "host": "127.0.0.1",
    "port": 5173
  },
  "middleware": [],
  "routeMiddleware": {
    "pages": [],
    "apis": [],
    "actions": []
  },
  "styling": {
    "globalStyles": [],
    "globalScripts": []
  },
  "cors": {
    "origins": [],
    "methods": ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
    "headers": [],
    "credentials": false,
    "maxAge": 600
  },
  "csrf": {
    "enabled": true,
    "headerName": "x-csrf-token",
    "cookieSecure": false,
    "cookieSameSite": "lax",
    "exemptPaths": []
  },
  "cache": {},
  "navigation": {},
  "rateLimit": {
    "requests": 0,
    "window": 60,
    "exemptPaths": [],
    "trustForwardedFor": false
  },
  "observability": {
    "requestId": true,
    "requestIdHeader": "X-Request-Id",
    "trustIncomingRequestId": false,
    "timing": true,
    "metricsEndpoint": false,
    "metricsEndpointPath": "/api/__pyxle/metrics",
    "metricsEndpointToken": null,
    "accessLog": false,
    "logFormat": "console",
    "logLevel": "INFO",
    "otel": false,
    "otelServiceName": "pyxle-app",
    "otelSampleRatio": 0.05
  },
  "llms": {
    "enabled": false,
    "autoConvert": false
  },
  "dev": {
    "watch": [],
    "ignore": []
  },
  "plugins": []
}

Directory settings

Server settings

starlette

vite

debug

Middleware

middleware

Application-level middleware classes applied to every request.

{
  "middleware": [
    "myapp.middleware:LoggingMiddleware",
    "myapp.middleware:TimingMiddleware"
  ]
}

Each entry is a "module.path:ClassName" string pointing to a Starlette-compatible middleware class.

routeMiddleware

Route-level hooks applied to specific route types.

{
  "routeMiddleware": {
    "pages": ["myapp.hooks:require_auth"],
    "apis": ["myapp.hooks:rate_limit"],
    "actions": ["myapp.hooks:require_auth_json"]
  }
}

Styling

styling

{
  "styling": {
    "globalStyles": ["styles/reset.css", "styles/typography.css"],
    "globalScripts": ["scripts/analytics.js"]
  }
}

CORS

{
  "cors": {
    "origins": ["https://app.example.com"],
    "methods": ["GET", "POST"],
    "headers": ["Authorization"],
    "credentials": true,
    "maxAge": 3600
  }
}

CSRF

{
  "csrf": {
    "enabled": true,
    "cookieName": "my-app-csrf",
    "headerName": "x-csrf-token",
    "cookieSecure": true,
    "cookieSameSite": "strict",
    "exemptPaths": ["/api/webhooks"]
  }
}

Cookie naming. Browsers scope cookies to a host, ignoring the port, so a fixed cookie name would collide between two Pyxle apps on the same host (e.g. two dev servers on 127.0.0.1) — each would overwrite the other's token and every action in the other app would fail with 403. When cookieName is unset, Pyxle namespaces the cookie with the app's bind port (pyxle-csrf-8000), which is stable per app in development and behind a production reverse proxy. Set cookieName to pin an explicit name instead. Full details and the upgrade note: Security → CSRF protection.

Exemption matching. An entry matches its exact path and anything beneath it at a / segment boundary: /api/webhooks exempts /api/webhooks and /api/webhooks/stripe, but not /api/webhooks-admin. Request paths are normalised first (./.. resolved, repeated slashes collapsed), so /api/webhooks/../other is checked as /api/other. An entry of / (or an empty string) is ignored rather than disabling CSRF site-wide — use "csrf": false to disable CSRF entirely.

Shorthand to disable: "csrf": false

Edge caching

Mark page routes that render no per-user data as publicly cacheable. A matched page is served Cache-Control: public, s-maxage=<seconds> (plus a stale-while-revalidate window) instead of the default private, no-cache, so a shared cache -- a CDN or reverse proxy -- can absorb the traffic instead of your origin. It's Pyxle's config-driven equivalent of Next.js per-route revalidation.

{
  "cache": {
    "/": 60,
    "/blog/*": 600,
    "/docs/*": { "sMaxage": 300 }
  }
}

Each key is a route pattern; each value is the shared-cache lifetime in seconds:

Matching. An exact path wins over a wildcard; among wildcards the longest (most specific) prefix wins. A pattern must be an absolute path. A wildcard (/docs/*) matches the bare prefix (/docs) and any segment beneath it (/docs/guides/intro), but not a path that merely shares the string (/docsearch).

A cacheable response carries no CSRF cookie. A per-user Set-Cookie must never ride on a response that a shared cache can replay to other users -- and most CDNs refuse to cache any response that sets a cookie at all. So on a cacheable route Pyxle omits the CSRF cookie, which means any @action reachable from that route must be exempt via csrf.exemptPaths. Only mark routes that render no per-user state and whose actions are safe to exempt.

Turning it on at the edge. These headers make a response eligible for shared caching, but some CDNs don't cache HTML by default. On Cloudflare, you must also add a Cache Rule ("Cache Everything") for the cached paths -- the headers alone are necessary but not sufficient. See Deployment → CDN and edge caching.

Navigation

Pyxle's client keeps an in-memory navigation cache so client-side navigation -- and the data prefetched when a <Link> scrolls into view or is hovered -- resolves instantly instead of refetching the loader. The page you land on is seeded into this cache from the server render, so its loader never runs a second time on the initial load.

{
  "navigation": {
    "defaultPrefetchTtl": 120
  }
}

A route listed in the cache block reuses its edge-cache TTL as its navigation-cache lifetime, overriding defaultPrefetchTtl for that route -- so a page's client freshness matches how long a CDN would serve it. (Consequence: raising a route's cache TTL also lengthens its edge cache, so purge the CDN on deploy -- which you should do regardless.) A dynamic page -- a @server loader with no cache entry -- is not navigation-cached at all (it renders private, no-cache), so back/forward always refetches and defaultPrefetchTtl does not apply to it; add a cache entry to opt such a page into navigation caching. After a mutation, the client router's invalidate(href) drops a cached entry so the next navigation refetches.

Rate limiting

A built-in token-bucket limiter. Disabled by default (requests: 0). Set requests to a positive number to cap how fast a single client may call the app.

{
  "rateLimit": {
    "requests": 100,
    "window": 60,
    "exemptPaths": ["/health"],
    "trustForwardedFor": false
  }
}

Burst vs. sustained. requests is the burst a client can spend at once; the bucket then refills at requests / window per second, so the long-run average is bounded without rejecting brief spikes. A blocked request gets 429 Too Many Requests with a Retry-After header.

Multi-worker caveat. The bucket store is in-memory and per-process, so under pyxle serve --workers N each worker enforces the limit independently and the effective global cap is N × requests. For a single shared limit, rate-limit at your reverse proxy or load balancer. See the middleware guide.

Observability

Request correlation IDs and timing. Both are on by default -- generating an id and reading two timestamps per request is sub-microsecond and adds no I/O, and every request gets a correlation key surfaced as the response header and on request.state.request_id (readable from any loader or @action). See the Observability guide.

{
  "observability": {
    "requestId": true,
    "requestIdHeader": "X-Request-Id",
    "trustIncomingRequestId": false,
    "timing": true,
    "metricsEndpoint": false,
    "metricsEndpointPath": "/api/__pyxle/metrics",
    "metricsEndpointToken": null
  }
}

Shorthand to disable request-id and timing: "observability": false. The page-cache hit-ratio metric requires the server-side page cache (active under pyxle serve). Multi-worker note: under pyxle serve --workers N each worker process exposes its own metrics (with a worker label), so aggregate across workers at the scraper.

AI accessibility

Serve a clean markdown rendition of every page — at its URL with .md appended, and to requests that send Accept: text/markdown — plus an /llms.txt index, so AI assistants and coding agents can read your app as text instead of parsing HTML. Off by default. See the AI accessibility guide for the full model.

{
  "llms": {
    "enabled": true,
    "autoConvert": false
  }
}

Where the markdown comes from is not config — it lives in your project, resolved in this order (first hit wins): a co-located <page>.md file → a to_markdown handler in the page's server module → a to_markdown in the nearest ancestor llms.py (covers a route subtree; pages/llms.py is app-wide) → autoConvert (if on) → otherwise the .md URL redirects to the page. A root pages/llms.py may also define wrap_markdown(ctx, markdown) to frame every .md response with a header/footer. Likewise /llms.txt comes from a static public/llms.txt, else a llms_txt function in the root pages/llms.py, else a generated index. See the guide.

Deploying handlers. Co-located .md files and llms.py handlers are part of your source, so they must be present alongside pages/ when you pyxle serve. (A page's own to_markdown, compiled into the build, works regardless.)

Development

The dev block tunes the pyxle dev file watcher. Both fields are dev-only — pyxle serve runs no watcher (it serves a pre-built, immutable tree), so they are ignored in production.

{
  "dev": {
    "watch": ["lib", "components"],
    "ignore": ["pages/generated/*", "*.tmp"]
  }
}

Why dev.watch. Pyxle only watches pages/ by default (unlike Next.js, which watches whatever the import graph touches). A shared Python module imported from outside pages/ — say lib/util.py used by a loader — would not otherwise trigger a reload when you edit it. Listing its directory here closes that gap.

dev.ignore is additive, never subtractive. Pyxle always ignores its own generated build output on the rebuild watch — compiled bytecode (*.pyc), .pyxle-build/__pycache__ trees, and SQLite journals (*.db, *.db-wal, *.db-shm). Those built-in ignores are load-bearing (they prevent a self-sustaining rebuild loop) and stay in force regardless of config — a dev.ignore list can only add more patterns, it cannot clear them.

Note on public/. Changes under public/ are never rebuilt or reloaded — static assets are served live from disk and picked up on the next refresh (like Next.js). You don't need to (and can't usefully) list public/ in dev.watch. See Architecture → the watcher.

Plugins

plugins

{
  "plugins": [
    "pyxle-db",
    {
      "name": "pyxle-auth",
      "module": "pyxle_auth.plugin",
      "attribute": "plugin",
      "settings": {
        "cookieDomain": ".pyxle.app",
        "strict": true
      }
    }
  ]
}

Each entry declares one plugin. Pyxle imports each plugin, calls its on_startup hook inside the ASGI lifespan, and exposes the services they register to loaders and actions.

Entries can be either a bare string or an object:

Plugin ordering matters. Plugins are started in the order you list them. List a plugin before any plugin that depends on it — e.g. pyxle-db before pyxle-auth, since auth needs a database.

See the Plugins guide for authoring and consuming patterns, and Plugins API reference for the full API.

First-party plugins:

• pyxle-db — SQLite-first database with migrations
• pyxle-auth — Email+password session auth

Environment variable overrides

These environment variables override config file values:

Precedence

From lowest to highest priority:

1. Pyxle defaults
2. pyxle.config.json
3. .env files
4. PYXLE_* environment variables
5. CLI flags (--host, --port, etc.)

Validation

Pyxle validates your config file at startup:

• Unknown keys are rejected with an error listing the invalid keys
• Port numbers must be between 1 and 65535
• Directory values must be non-empty strings
• Middleware entries must be non-empty "module:Class" strings
• CORS and CSRF sub-fields are type-checked
• Cache routes must be absolute-path patterns mapping to a non-negative integer lifetime