Getting started

Installation

Clone, install, run — and the environment variables you can skip.

Requirements

Node 20 or newer and npm. Nothing else is required to run the template locally — every cloud integration is optional.

Run the template

Bash

npm install
npm run dev

The dev server starts on http://localhost:3000 with no environment variables set. Auth screens render, but submitting them reports that authentication is not configured rather than throwing.

Scaffold an app instead

To generate a project containing only the surfaces you want, use the scaffolder rather than deleting code from a clone:

Bash

node scripts/scaffold.mjs --surfaces landing,docs --out ../my-site --name my-site

See Scaffolding for the full flag list and the guarantees the generated project carries. Without a clone, the Once UI CLI creates the same app from the command line.

Environment variables

Copy .env.example to .env.local and fill in only what you need. Each variable belongs to a capability slice; a project scaffolded without that slice will not list it at all.

Bash

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
SUPABASE_SECRET_KEY=
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

The Supabase keys enable sign-in and the profile routes. The Upstash keys enable rate limiting on those routes; without them the routes still work and simply are not rate limited. Never expose the service role key to the browser — it is read only in server code under src/lib/sb.