Local Development

Prerequisites

Node.js LTS (v20+)
npm v10+
A Cloudflare developer account (for preview environments)
Wrangler CLI: npm install -g wrangler

Setup

Clone the repository and install dependencies:

npm install

Create .env.local in the project root with your local dev values:

NEXT_PUBLIC_AUTH_BYPASS=true
OPENAI_API_KEY=sk-...           # Optional — used for dev AI testing
GOOGLE_GENERATIVE_AI_API_KEY=...
SMTP2GO_API_KEY=dev             # "dev" = OTP codes logged to console
STRIPE_SECRET_KEY=sk_test_...   # Stripe test mode key
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRO_PRICE_ID=price_...

Never commit .env.local. It is in .gitignore.

Start the dev server:

npm run dev

The app runs at http://localhost:3000.

Auth bypass mode

Setting NEXT_PUBLIC_AUTH_BYPASS=true skips the OTP login flow:

The middleware auto-sets a dev session cookie for dev@localhost.
The login page redirects directly to the dashboard.
Board access checks are skipped.
OTP emails are logged to the console instead of being sent.

This makes local iteration fast without needing a real email inbox.

Local vs preview modes

Mode	When to use	Backend
Auth bypass + no D1	UI-only iteration	In-memory only (no server persistence)
Local Wrangler dev	Testing sync, auth, billing	Local Cloudflare emulation via Wrangler
Preview environment	Full-stack integration testing	Preview Workers + Preview D1

To run with the Cloudflare context locally:

npx wrangler dev --local

Or use the @cloudflare/next-on-pages dev emulation (configured in next.config.mjs).

Common commands

Command	Description
`npm run dev`	Next.js dev server (port 3000)
`npm run build`	Production build
`npm run lint`	ESLint checks
`npm run deploy`	Build + deploy to Cloudflare Workers
`npm run predeploy`	Pre-deploy validation checks only
`npm run cf-typegen`	Regenerate `cloudflare-env.d.ts` from `wrangler.jsonc`

Local dev guardrails

Never commit secrets — .env.local is in .gitignore.
Never enable auth bypass in production — NEXT_PUBLIC_AUTH_BYPASS must not be set in deployed environments.
Keep wrangler secrets separate from .env.local — production secrets are managed via wrangler secret put.

Applying database migrations locally

npx wrangler d1 migrations apply sticky-notes-db --local

For a remote preview environment:

npx wrangler d1 migrations apply sticky-notes-db --remote