Routing

Pyxle uses file-based routing. The file structure inside your pages/ directory determines the URL routes of your application. No router configuration is needed.

Basic routes

Every .pyxl file in pages/ becomes a route:

The index.pyxl filename is special -- it maps to the parent directory's path.

Dynamic segments

Wrap a filename segment in square brackets to create a dynamic route parameter:

Access dynamic parameters in your loader via request.path_params:

@server
async def load_post(request):
    slug = request.path_params["slug"]
    post = await fetch_post(slug)
    return {"post": post}

export default function BlogPost({ data }) {
  return <h1>{data.post.title}</h1>;
}

Parameter name rules

• Hyphens in parameter names become underscores: [user-id].pyxl --> request.path_params["user_id"]
• The parameter name is sanitised to be a valid Python identifier

Catch-all routes

Use [...param].pyxl to match any number of path segments:

The parameter captures the entire remaining path as a string:

@server
async def load_docs(request):
    slug = request.path_params["slug"]  # "getting-started" or "api/config"
    return {"slug": slug}

Optional catch-all routes

Use [[...param]].pyxl (double brackets) to match the parent path and any sub-paths:

This creates two routes: one for the exact parent path and one for the catch-all.

Route groups

Wrap a directory name in parentheses to exclude it from the URL:

pages/
  (marketing)/
    pricing.pyxl      -->  /pricing     (not /marketing/pricing)
    features.pyxl     -->  /features
  (dashboard)/
    settings.pyxl     -->  /settings
    profile.pyxl      -->  /profile

Route groups let you organise files by concern without affecting URLs.

API routes

Python files under pages/api/ become API endpoints:

API routes are standard Python files (not .pyxl). See API Routes for details.

Viewing your route table

Run pyxle routes to see all registered routes:

pyxle routes

# Or as JSON:
pyxle routes --json

Special files

These filenames have special meaning and do not create their own routes:

See Layouts and Error Handling.

Next steps

• Load data for your pages: Data Loading
• Wrap pages in shared layouts: Layouts