Skip to content

Build the first application

This path creates one tested application for local ASGI/SQLite and native Cloudflare Workers/D1, with OpenAPI 3.1.1, MCP 2026-07-28 discovery and tools, Cloudflare Access, checked SQL, request correlation, and production middleware.

1. Generate

Install uv, then run:

uvx --refresh --from create-hayate==0.14.0 \
  create-hayate my-app --template workers --preset production
cd my-app

The version is intentional. Check the compatibility snapshot before changing individual pre-1.0 package pins.

2. Lock and verify

uv sync
test -f uv.lock
uv sync --locked
uv run pytest
uv run ruff check .
uv run python scripts/check_sql_contracts.py
sh scripts/export_api.sh
test -f openapi.json
test -f client/api-types.ts
test -f client/api-client.ts

Commit uv.lock and use uv sync --locked in CI. The generated .dev.vars contains ignored local development identity values; never commit production credentials.

3. Read the shape

  • src/app.py is the portable application core.
  • Uvicorn supplies local ASGI; SQLite supplies local data.
  • Workerd supplies the native Workers adapter; D1 is a runtime binding.
  • HTTP and MCP share request identity and checked storage.
  • client/api-types.ts and the callable client/api-client.ts come from the same OpenAPI document. The client uses platform Fetch APIs and adds no runtime package dependency.
  • The default Workers export is a WorkerEntrypoint class, preserving named RPC and class handlers such as scheduled.
  • Every response identifies the application release with X-Hayate-App-Version. Native Workers responses also expose Cloudflare's immutable deployment UUID as X-Hayate-Worker-Version; local ASGI responses intentionally omit it.
  • Protected production requests fail closed when either required deployment identity is absent. CORS exposes both identifiers only to the configured exact origin.

ASGI is not involved in the native Workers path.

4. Prepare production

Compare the result with the golden application, then complete its production checklist and read its trust boundaries.

Do not deploy placeholder Access audiences, D1 identifiers, CORS origins, rate-limit namespaces, or observability policy.