Environment Variables

Pyxle loads environment variables from .env files and supports special prefixes for configuration overrides and client-side injection.

.env files

Create .env files in your project root:

# .env -- base defaults (commit to source control)
DATABASE_URL=postgres://localhost/mydb
API_KEY=dev-key-123
PYXLE_PUBLIC_APP_NAME=My App

Load order

Files are loaded in order of increasing precedence. Later files override earlier ones:

1. .env -- base defaults
2. .env.development or .env.production -- mode-specific
3. .env.local -- local overrides (gitignore this)
4. .env.development.local or .env.production.local -- local mode overrides

The mode is development when running pyxle dev and production when running pyxle build or pyxle serve.

The shell always wins

Variables already set in your shell environment are never overwritten by .env files. This means CI/CD environment variables and Docker env take precedence.

Syntax

# Simple values
KEY=value

# Quoted values
KEY="value with spaces"
KEY='literal value (no escape processing)'

# Optional export prefix
export KEY=value

# Comments
# This is a comment
KEY=value  # Inline comments work too (unquoted values only)

Double-quoted values support escape sequences: \", \n, \r, \t, \\.

PYXLE_PUBLIC_ prefix

Variables starting with PYXLE_PUBLIC_ are injected into client-side JavaScript at build time:

# .env
PYXLE_PUBLIC_API_URL=https://api.example.com
PYXLE_PUBLIC_APP_VERSION=1.2.3

Access them in your JSX via import.meta.env:

export default function Page() {
  return <p>API: {import.meta.env.PYXLE_PUBLIC_API_URL}</p>;
}

The value is substituted at build time into both the server (SSR) and client bundles, so it's safe to render directly into initial HTML — the server and client agree, with no hydration mismatch.

Server-only variables (without the PYXLE_PUBLIC_ prefix) are never exposed to the client. They are only available via os.environ in your Python code.

PYXLE_ config overrides

These environment variables override settings from pyxle.config.json:

Precedence

From lowest to highest:

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

Page cache backend

These select where the server-side page cache stores rendered HTML. The default needs no configuration.

The cache is active only for production serves (pyxle serve); pyxle dev never caches. The redis backend needs pip install 'pyxle-framework[redis]'.

Realtime broker

These select the WebSocket pub/sub broker. The default in-process broker needs no configuration; switch to Redis for cross-worker delivery under pyxle serve --workers N.

The redis broker needs pip install 'pyxle-framework[redis]'.

SSR rendering

These tune the server-side rendering worker pool. The number of SSR processes is set with pyxle serve --ssr-workers (auto-sized by default); this variable tunes how many renders each of those processes runs concurrently.

Using environment variables in loaders

import os

@server
async def load_page(request):
    api_key = os.environ.get("API_KEY", "")
    # Use api_key to call an external service
    return {"data": "..."}

.env files are loaded by the Pyxle CLI at startup (pyxle dev/serve/build). Outside the CLI — e.g. a loader unit-tested in isolation, or python app.py — they are not auto-loaded; set the variables in the process environment yourself or call pyxle.env.load_env_files() first.

.gitignore recommendations

# Commit these
.env
.env.development
.env.production

# Do NOT commit these (contain secrets)
.env.local
.env.*.local

Next steps

• Handle errors gracefully: Error Handling
• Secure your app: Security