Quickstart - Overlay Web

Prerequisites

Node.js 20 or newer.
npm.
Access to the development Convex deployment.
WorkOS credentials for sign-in flows.
Stripe test credentials when testing billing.

What This Runs

The local web app starts the Next.js browser shell, /api/v1 route wrappers, server-side provider adapters, and Convex-backed app state. External processors such as browser automation, sandboxes, web search, analytics, and error reporting are controlled by runtime config and can be disabled for private deployments.

Install

npm install
cp .env.example .env.local

Fill in the required web environment variables before starting the app. For local web work against the development backend, prefer:

npm run dev:with-convex

This pushes the development Convex deployment first, then starts next dev.

First successful boot

A healthy local boot should show:

Next.js serving the app on localhost:3000.
No runtime config error page.
Sign-in redirects using the configured WorkOS app.
/api/v1/capabilities returning capability metadata.
/api/v1/bootstrap returning signed-in app state after authentication.

Verify changes

Use the smallest check that covers the change:

npm run typecheck
npm run lint
npm run build

For docs changes:

npm run docs:check

Overlay Web Repository Map

​Prerequisites

​What This Runs

​Install

​First successful boot

​Verify changes

Prerequisites

What This Runs

Install

First successful boot

Verify changes