nyxa

Batteries-included DX for Python API backends on FastAPI.

Nyxa is pronounced Nik-sah (/ˈnɪksə/). Site: nyxadev.com · Repo: NyxaDev/nyxa.

Nyxa gives you a convention-based CLI (nyxa, with an artisan alias), project layout, central routes.py + controllers, and small runtime bases (AppError, abort helpers, register, events). It is backend/API only — no server-side templates, Vite, or frontend stack.

Long-term plans: see the workspace roadmap/.

Install

uv add nyxa
# or
pip install nyxa

The import and CLI stay nyxa:

from nyxa import AppError, Route, register

Quick start

uvx --from nyxa nyxa new myapp
cd myapp
uv sync
uv run dev

Interactive mode (TTY) prompts for database, auth, and optional packs. For CI:

nyxa new myapp --database sqlite --auth none --no-input

Cheat sheet: docs/cheat-sheet.md. Adapter upgrades: docs/upgrading.md.

CORS and logging

Optional; off by default. Configure in nyxa.toml or env — applied inside register():

[cors]
origins = ["http://localhost:3000"]

[logging]
json = true
level = "INFO"

CORS_ORIGINS=http://localhost:3000
NYXA_LOG_JSON=1

Or call configure_cors(app, origins=[...]) / configure_logging() manually.

Scaffold into the current directory:

mkdir myapp && cd myapp
uvx --from nyxa nyxa init

Monorepo / unpublished local checkout:

uv run nyxa new myapp --nyxa-path /path/to/packages/nyxa

Routing

Define routes in src/{app}/routes.py. Nyxa compiles them at startup into normal FastAPI endpoints (no Route stack on the request hot path).

# src/myapp/routes.py
from nyxa.routing import Route
from myapp.http.controllers.user_controller import UserController

with Route.prefix("/api"):
    Route.resource("users", UserController)

Stable CLI (0.1)

Entry points: nyxa, artisan (alias), and dev.

Generated scaffolds include Google-style docstrings (Args / Returns) on modules, classes, and functions.

Stable public API (0.1)

Supported imports for application code:

from nyxa import (
    AppError,
    Controller,
    EventDispatcher,
    ForbiddenError,
    FormRequest,
    Route,
    ServiceProvider,
    abort,
    bind,
    check,
    config,
    context,
    current_user,
    dispatcher,
    env,
    guest,
    no_content,
    not_found,
    register,
    route,
    settings,
    success,
    user,
)

Everything else under nyxa.* (templates, generate, make, config internals, …) is private and may change without notice.

See also API.md.

Config (nyxa.toml, optional)

All keys optional. Defaults:

app = "myapp"       # required in practice — set by `init` / `new`
src = "src"

[dev]
module = "myapp.main:app"   # default: "{app}.main:app"
host = "0.0.0.0"
port = 8000
reload = true

[paths]
errors = "http/exception/errors"
handlers = "http/exception/handlers"
requests = "http/requests"
responses = "http/responses"
middleware = "http/middleware"
controllers = "http/controllers"
dependencies = "http/dependencies"
services = "services"
schemas = "schemas"
enums = "domain/enums"
config = "config"
events = "events"
listeners = "listeners"
jobs = "jobs"
providers = "providers"
tests = "tests"             # relative to project root

[middleware]
# global = ["timing"]       # optional Kernel-style list (module stems); request-inbound order
# When unset, all http/middleware/*/Middleware exports are auto-discovered (alphabetical).

[providers]
# boot = ["app_service_provider"]  # optional ordered list (module stems under paths.providers)
# When unset, all providers/*/Provider exports are auto-discovered (alphabetical).

[env]
file = ".env"               # primary dotenv under project root
# environment = "local"     # also load .env.{environment}; else NYXA_ENV / APP_ENV

[bases]
error = "nyxa.errors:AppError"

Fallback: [tool.nyxa] app = "..." in pyproject.toml.

Middleware (two concepts)

Use [middleware] global = ["timing", ...] for an explicit Kernel-style order (first entry is outermost / sees the request first). Omit global to auto-discover all modules alphabetically.

Service providers

App boot hooks under providers/. Each module exports Provider (a ServiceProvider subclass) with optional register / boot methods. register(app) calls all register hooks, then all boot hooks, before loading routes.py.

uv run nyxa make:provider AppService

[providers]
boot = ["app_service_provider"]  # optional; omit for alphabetical discovery

Service container

Lean bind/resolve for app-scoped services. Bind in a provider; inject via FastAPI:

from nyxa import singleton, inject

# in ServiceProvider.register:
singleton(UserService)

# in controller __init__:
service: Annotated[UserService, Depends(inject(UserService))]

Also: bind, instance, make / resolve, has. The global container is flushed at the start of each register().

Environment (.env)

register(app) loads dotenv files into the process environment:

1. Primary file from [env] file (default .env)
2. Optional .env.{environment} when [env] environment is set, else NYXA_ENV, else APP_ENV

Among files, the environment-specific file overrides the primary for shared keys. Existing OS/CI variables are never overridden. Missing files are no-ops. init / new write .env.example as a template — copy to .env (and optionally .env.local, etc.) locally (gitignored).

[env]
file = ".env"
environment = "local"   # loads .env then .env.local

Out of scope (for now)

• Database / migrations — Phase 2 (nyxa-db) — Done
• Auth / policies — Phase 3 (nyxa-auth) — Done (JWT, sessions, personal tokens, Google OAuth)
• Queues, cache, mail, storage — Phase 4 Done (nyxa-queue, nyxa-cache, nyxa-mail, nyxa-storage)
• Frontend scaffolding — never (API-only)

Tests

# from workspace root
uv sync --group dev
uv run pytest packages/nyxa/tests

Publish (maintainers)

GitHub Release (recommended)

.github/workflows/publish-nyxa.yml publishes core nyxa and all seven nyxa-* packs from one Release tag, using PyPI Trusted Publishing (OIDC, no API token secret).

One-time setup

1. In GitHub → Settings → Environments, create one environment per package: pypi-nyxa, pypi-nyxa-db, pypi-nyxa-auth, pypi-nyxa-queue, pypi-nyxa-cache, pypi-nyxa-mail, pypi-nyxa-storage, pypi-nyxa-postgres.
2. On PyPI, add a Trusted Publisher for each package (GitHub tab):

For a project that doesn't exist yet, register it as a pending publisher at pypi.org/manage/account/publishing. PyPI allows 3 pending publishers per account at a time, and each slot frees up once its project is created. Pending publishers must also be unique on owner/repo/workflow/environment, which is why every package has its own environment.

Each release

gh release create v0.1.1 --target master --title "Nyxa v0.1.1" --notes "…"
gh run watch

The tag (leading v stripped) becomes the version of every packages/nyxa*/pyproject.toml. The workflow builds all eight packages once, then runs one publish job per package in its own environment. A failed job can be re-run with gh run rerun <run-id> --failed; files already on PyPI are skipped.

Verify a build locally

From the workspace root, build exactly as CI does, then install the wheels into a scratch environment:

for p in nyxa nyxa-db nyxa-auth nyxa-queue nyxa-cache nyxa-mail nyxa-storage nyxa-postgres; do
  uv build --package "$p" --no-sources --out-dir /tmp/nyxa-dist
done
uvx twine check /tmp/nyxa-dist/*
uvx --from /tmp/nyxa-dist/nyxa-0.1.0-py3-none-any.whl nyxa new /tmp/demoapp --no-input
# resolve the scaffold against local wheels before they are on PyPI:
cd /tmp/demoapp && uv sync --find-links /tmp/nyxa-dist

Roadmap

Workspace plans: roadmap/README.md.