Skip to main content
This guide walks through setting up the Umbra frontend for local development.

​
Prerequisites

  • Node.js 22 or later
  • pnpm 10.15.1 (pinned in package.json)
  • Supabase project (for authentication and waitlist)

​
Installation

1

Install dependencies

Install all required packages using pnpm:
pnpm install
The Makefile detects whether pnpm is available and falls back to npm if needed. pnpm matches the CI environment.
2

Configure environment

Copy the environment template and fill in required variables:
cp .env.example .env.local
Generate a strong FORM_TOKEN_SECRET:
openssl rand -hex 32
Never commit .env.local to version control. It contains sensitive credentials.
See Environment Variables for a complete reference.
3

Set up Supabase

  1. Create a Supabase project at supabase.com
  2. Add callback URLs to Authentication → URL Configuration:
    • http://localhost:3000/auth/callback (development)
    • Your production domain callback URL
  3. Record these values in .env.local:
    • NEXT_PUBLIC_SUPABASE_URL - Your project URL
    • NEXT_PUBLIC_SUPABASE_ANON_KEY - Public anon key
    • SUPABASE_SERVICE_ROLE_KEY - Service role key (keep server-side only)
  4. Run the SQL schema to create the waitlist table: Execute supabase/schema.sql in the Supabase SQL editor or via psql to create:
    • waitlist_requests table
    • waitlist_status enum
    • Indexes and RLS policies
  5. Seed at least one admin user: 
    update auth.users
set raw_app_meta_data = jsonb_set(
  coalesce(raw_app_meta_data, '{}'),
  '{roles}',
  '["admin"]'::jsonb,
  true
)
where email = '[email protected]';
  6. (Optional) Tag beta users with member role so they can sign in without consuming guest sessions: 
    update auth.users
set raw_app_meta_data = jsonb_set(
  coalesce(raw_app_meta_data, '{}'),
  '{roles}',
  '["member"]'::jsonb,
  true
)
where email = '[email protected]';
4

Run local development server

Start the Next.js development server:
pnpm dev --hostname 0.0.0.0 --port 3000
The app will be available at http://localhost:3000.make dev-open waits for the server to be ready and automatically opens the browser.
5

Build for production

Create an optimized production build:
pnpm build && pnpm start
The production server respects the PORT environment variable:
make start PORT=4000

​
Useful Commands

CommandPurpose
pnpm lintRun ESLint with Next.js rules
pnpm test:unitExecute Vitest unit tests
pnpm test:e2eRun Playwright E2E test suite
make testRun full test suite with required env vars
make cleanRemove .next build output
See Testing for detailed test execution instructions.

​
Operational Tips

​
Reset Workspace State

  • Hero prompt + attachments: Stored in sessionStorage keys hero-initial-message and hero-uploaded-files
  • Provider defaults: Stored in localStorage key confidential-provider-settings-v1
  • Provider tokens: Stored in sessionStorage key confidential-provider-token
Clear these keys in browser DevTools to reset the workspace.

​
Update System Prompt

Edit lib/system-prompt.ts or set NEXT_PUBLIC_DEFAULT_SYSTEM_PROMPT environment variable to override the Umbra persona.

​
Waitlist Status Flow

Statuses defined in lib/waitlist.ts: requested → contacted → invited → activated → archived

​
Theme Customization

Tailwind tokens are centralized in styles/globals.css. Use CSS variables instead of hard-coded colors when creating new components.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us