Moxie runtime API

During a request, handlers run with a moxie instance attached to global. This page summarizes the pieces you touch most often in index.js, frameworks, and helpers.

Accessing context

const { moxie } = global

const request = moxie.request    // method, path, body, querystrings, headers
const identity = moxie.identity  // site, path, env, flags, urls, hosts
const settings = moxie.settings  // routes, sites, env, caching, specs

Use identity for environment-aware URLs and site-specific behavior. Use settings for route tables and merged policy objects (caching, specs) loaded at boot.

Errors

moxie.throw(...) — throw a structured MoxieError consumed by the top-level handler in src/index.ts. Prefer this over raw Error for consistent API error bodies.
generate.crash(...) (from helpers) — build standard error responses where that utility applies.

Keep user-facing messages and internal details aligned with team standards; avoid leaking stack traces in prod responses.

Logging

moxie.log(type, message, body, include_benchmox) — structured logs accumulated in moxie.logs for the request lifecycle.
Do not rely on console.log in committed code — Biome / hooks discourage it, and logs are harder to correlate in Lambda.

Debugging flags

moxie.debugga(flag) — returns whether a given flag is active for this request (from ?debugga= querystring).
Users can pass comma-separated flags: ?debugga=route,config,mapping.
?debugga=debuggas lists available keys (see Debugging).

Use debugga in handlers to append diagnostics only when requested, keeping normal responses lean.

Composition

moxie.parse(...) — used in flows where a handler or framework delegates to another layer with optional parse(route, config, data) on modules.

Exact signatures follow patterns in @app/frameworks/jsonapi and endpoint base classes — read an adjacent endpoint in the same group when adding new code.

Storage & HTTP

Moxie exposes storage helpers and clients for S3 and outbound HTTP (often via Hypertext and named clients). See External clients and Static files & S3.

Benchmox / timing

Optional benchmox integration can attach timing data to logs when enabled — pass include_benchmox where moxie.log supports it for performance investigations.

Architecture — where Moxie sits in the pipeline.
Conventions — naming and payload rules.