App Initialization

Every PyWire project starts with an application instance. This is typically defined in a file named app.py or main.py in your project root.

The PyWire Class

The PyWire class is the main entry point. It initializes the ASGI application, the router, and the compilation engine.

main.py

from pywire import PyWire

app = PyWire()

Configuration Options

You can customize the application behavior by passing arguments to the constructor:

app = PyWire(
    # Directory (relative to project root) containing your .wire pages (default: "pages")
    pages_dir="src/pages",

    # Enable file-system based routing (default: True)
    path_based_routing=True,

    # Enable PJAX (smooth page transitions) (default: True)
    enable_pjax=True,

    # Enable debug mode (exposes source maps, etc.) (default: False)
    debug=True,

    # URL prefix for serving static files (default: "/static")
    static_route="/assets",

    # ASGI middleware (default: None). See the Middleware guide.
    middleware=[CORSMiddleware],

    # Disable WebSocket for HTTP-only deployments (default: True).
    # See the Deployment guide for details.
    interactive_server_mode=True,

    # Return bare 404 for unmatched paths when mounted in a host framework
    # (default: False). See the Framework Integration guide.
    fallthrough_404=False,
)

Middleware

PyWire supports standard ASGI middleware. Pass middleware classes (or (class, options) tuples) to the middleware parameter, or use app.add_middleware() after construction:

from starlette.middleware.cors import CORSMiddleware

app = PyWire(
    middleware=[
        (CORSMiddleware, {"allow_origins": ["*"]}),
    ],
)

See the Middleware guide for full details.

Running the App

Development

When you run pywire dev, the CLI automatically looks for a module exposing an app variable that is an instance of PyWire.

# Auto-discovery
pywire dev

# Explicit pointer
pywire dev src.main:app

# No TUI
pywire dev --no-tui

Production

For production, you use pywire run, which wraps Uvicorn.

pywire run src.main:app --workers 4

Serving Static Files

If you have a static/ directory in your project root, PyWire will automatically serve files from it at the /static URL prefix.

Example structure:

project/
├── static/
│   ├── logo.png
│   └── styles.css
├── pages/
└── main.py

You can reference these in your templates:

<img src="/static/logo.png" alt="Logo" />