Skip to content

getting-started.md

Latest commit

 

History

History
147 lines (106 loc) · 5.96 KB

getting-started.md

File metadata and controls

147 lines (106 loc) · 5.96 KB
Raw

Getting Started

Documentation home · API reference · Testing · Deployment

This guide takes a clean checkout to a running local Worker and explains which configuration belongs to development, automated tests, and production.

Requirements

Tool Minimum Notes
Node.js 22 The repository .nvmrc selects the supported major version
pnpm 11.13 Provisioned through Corepack; dependencies use pnpm-lock.yaml
Python 3.12 recommended Required only for Requests and HTTPX contract tests
curl Current stable Required by the command-line client contract test
Chromium Playwright-managed Installed through the project test tooling

Wrangler, Vitest, Playwright, TypeScript, and linting tools are project dependencies. Do not install global copies.

Install

corepack enable
pnpm install --frozen-lockfile
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-contract.txt
pnpm exec playwright install chromium
cp .dev.vars.example .dev.vars
pnpm run types

Use pnpm install without --frozen-lockfile only when intentionally changing dependencies and the lockfile.

Local configuration

.dev.vars is ignored by Git and provides interactive development values:

ENVIRONMENT=development
CHALLENGE_SIGNING_KEY=replace-with-a-long-random-local-test-key

Keep local values synthetic. Never copy a production signing key into the repository or a shared command transcript.

The configuration layers are intentionally separate:

Context Source Environment
Interactive pnpm run dev Ignored .dev.vars Development
Automated local and CI tests Committed .dev.vars.example Development with synthetic key
Binding type generation Empty .wrangler.types.env Stable config-derived types
Owner-run deployment wrangler.jsonc plus Wrangler secrets Production

Run the Worker

pnpm run dev

Wrangler starts workerd locally and prints the listening URL, normally http://localhost:8787.

flowchart LR
    Request["localhost request"] --> Wrangler["Wrangler + workerd"]
    Wrangler --> Worker["Hono Worker"]
    Worker --> Assets["Local static assets"]
    Worker --> LocalDO[("Local ChallengeSequence")]
    Worker --> Response["Fixture response"]
Loading

Useful first requests:

curl http://localhost:8787/health
curl 'http://localhost:8787/get?tag=one&tag=two'
curl -i http://localhost:8787/status/418

Open http://localhost:8787/ for the searchable directory, /docs for the comprehensive service guide, /browser for browser fixtures, and /challenge for synthetic challenges.

Common workflows

Goal Command
Start interactive development pnpm run dev
Regenerate Worker binding types pnpm run types
Run unit and Worker tests pnpm test
Run browser fixtures in Chromium pnpm run test:browser
Run the complete CI-equivalent gate pnpm run validate
Build without publishing pnpm run build
Perform deployment preflight pnpm run deploy:dry-run

Automated test scripts start isolated local Workers with the committed synthetic test environment, so CI does not depend on an operator's .dev.vars.

Repository orientation

src/                  Worker application
  routes/             HTTP, browser, challenge, and system transports
  schemas/            Public input/output schemas
  services/           Fixture behavior and shared policy
  middleware/         Cross-cutting request behavior
  durable-objects/    Sequence coordination
public/               Browser fixture assets
test/                 Unit, integration, contract, and browser tests
scripts/              Contract, wire, smoke, and documentation checks
docs/                 Project wiki and endpoint contracts

The architecture guide explains these boundaries and the request lifecycle in detail.

Troubleshooting

Wrangler reports a missing challenge key

Confirm .dev.vars exists and contains a synthetic CHALLENGE_SIGNING_KEY of at least 32 characters so local configuration matches production shape. Development runtime behavior has a synthetic fallback, but production challenge routes deliberately fail closed when the owner-managed secret is absent or too short.

Playwright cannot find Chromium

pnpm exec playwright install chromium

On CI Linux, the workflow uses pnpm exec playwright install --with-deps chromium to install browser system dependencies as well.

Python contract tests cannot import Requests or HTTPX

.venv/bin/python -m pip install -r requirements-contract.txt

Activate .venv, or ensure the Python selected by the test environment has the pinned requirements installed.

Generated Worker types are stale

pnpm run types
pnpm run typecheck

Commit worker-configuration.d.ts when a binding change intentionally updates it.

Next steps