Getting Started Runbook

This runbook covers local development setup for a Factory app Worker.

Prerequisites

Node.js 20+
Wrangler CLI (npm install -g wrangler)
Access to the GitHub Packages registry (@latimer-woods-tech/*)
Neon Postgres connection string (or access to factory-admin to retrieve it)

1. Clone the repo

git clone https://github.com/Latimer-Woods-Tech/{app}.git
cd {app}

2. Authenticate with GitHub Packages

Create (or reuse) a GitHub Personal Access Token with read:packages scope.

# ~/.npmrc or .npmrc in project root
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
@latimer-woods-tech:registry=https://npm.pkg.github.com

3. Install dependencies

npm install

4. Create `.dev.vars`

Wrangler loads .dev.vars as secrets during wrangler dev. Never commit this file.

# .dev.vars
JWT_SECRET=dev-secret-change-in-production
DATABASE_URL=postgresql://user:pass@host/db?sslmode=require
ANTHROPIC_API_KEY=sk-ant-...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
SENTRY_DSN=https://...@sentry.io/...
POSTHOG_KEY=phc_...

For app-specific bindings (Hyperdrive, KV, R2), add them to wrangler.jsonc under [dev] bindings or use remote dev mode (wrangler dev --remote).

5. Verify local environment configuration

Before starting the Worker, run the app’s environment verification if it exists. This catches missing bindings, wrong secret names, and environment mixups before wrangler dev starts.

node scripts/phase-6-setup.js --verify-local

If the app uses a different verifier, follow its README and Environment Verification Setup.

6. Start the local dev server

npm run dev
# or
wrangler dev

The Worker is available at http://localhost:8787.

7. Verify the health endpoint

curl http://localhost:8787/health
# {"status":"ok","service":"{app}","version":"x.y.z"}

8. Running tests

npm test
# with coverage
npm run test:coverage

9. TypeScript typecheck

npm run typecheck

Troubleshooting

Problem	Fix
`401 Unauthorized` on npm install	Re-check GitHub PAT scope and `.npmrc`
`ETARGET No matching version`	Run `npm install @latimer-woods-tech/{pkg}@latest`
Wrangler `InvalidSymbol` in wrangler.jsonc	Ensure all JSON keys are quoted
`process.env` not available	Use `c.env.VAR` / `env.VAR` (Cloudflare bindings only)
`Buffer is not defined`	Replace with `TextEncoder` / `Uint8Array`
Environment mismatch or missing binding	Run the local verifier and compare with Environment Verification Setup

Get Started

Platform Truth

Architecture

Foundations

Payments

AI

Telephony

Operations

Marketing

Revenue Ops

Runbooks

Governance

Getting started

Getting Started Runbook

Prerequisites

1. Clone the repo

2. Authenticate with GitHub Packages

3. Install dependencies

4. Create `.dev.vars`

5. Verify local environment configuration

6. Start the local dev server

7. Verify the health endpoint

8. Running tests

9. TypeScript typecheck

Troubleshooting

​Getting Started Runbook

​Prerequisites

​1. Clone the repo

​2. Authenticate with GitHub Packages

​3. Install dependencies

​4. Create .dev.vars

​5. Verify local environment configuration

​6. Start the local dev server

​7. Verify the health endpoint

​8. Running tests

​9. TypeScript typecheck

​Troubleshooting

Getting Started Runbook

Prerequisites

1. Clone the repo

2. Authenticate with GitHub Packages

3. Install dependencies

4. Create `.dev.vars`

5. Verify local environment configuration

6. Start the local dev server

7. Verify the health endpoint

8. Running tests

9. TypeScript typecheck

Troubleshooting