Web Setup

This guide covers setting up the Soundcheck web application for local development.

Prerequisites

Node.js 20+ (recommended: use nvm)
npm, yarn, pnpm, or bun
Git

Quick start

Navigate to web directory

cd web

Install dependencies

npm install

Set up environment variables

cp .env.example .env.local

Edit .env.local with your configuration:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_key
CLERK_SECRET_KEY=your_clerk_secret
NEXT_PUBLIC_API_URL=/api-proxy/api/v1
BACKEND_API_URL=http://localhost:4000

Start the development server

npm run dev

Open in browser

Navigate to http://localhost:3000

Environment variables

Required variables

Variable	Description
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Clerk public key for authentication
`CLERK_SECRET_KEY`	Clerk secret key for server-side auth
`NEXT_PUBLIC_API_URL`	API base URL (`/api-proxy/api/v1` for local dev proxy)

Optional variables

Variable	Description
`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`	Google Maps integration
`NEXT_PUBLIC_GTM_ID`	Google Tag Manager
`NEXT_PUBLIC_FF_*`	Optional local feature-flag overrides (`true`/`false`). The list in `web/.env.example` is generated from `flags/registry.json`

Feature flags

useFeatureFlag resolves in this order:

Session override from the header beaker menu (this browser, persisted as sc.dev.feature-flag-overrides)
NEXT_PUBLIC_FF_* environment variables
PostHog
Off

The header menu is always available in development (NEXT_PUBLIC_ENVIRONMENT / NODE_ENV is development). In QA and production it is gated by the feature-flag-overrides PostHog flag (or NEXT_PUBLIC_FF_FEATURE_FLAG_OVERRIDES), enabled for person emails containing @soundchecklive (same internal-only pattern as finances-csv-export). On/Off shows the value applied in this browser; a local marker and per-flag reset appear when that value is forced. Reset all restores env/PostHog defaults. The gate flag itself cannot be session-overridden, so localStorage cannot unlock the menu. For Azure builds, configure NEXT_PUBLIC_FF_FEATURE_FLAG_OVERRIDES as a GitHub environment variable before building the image. The workflow forwards it into the Docker build; changing only the running app configuration does not update this client-side value. Route guards wait for stored overrides and the access gate to resolve. If browser storage is unavailable, overrides work in memory until the page reloads.

Running with backend

For full functionality, run the web app alongside api-events:

Start shared infrastructure and API

In a separate terminal:

npm run dev:infra
cd api-events && npm run db:migrate && npm run dev:emulator

Start the web app

cd web
npm run dev:emulator

Access points

Service	URL
Web App	http://localhost:3000
api-events	http://localhost:4000

Development scripts

Core commands

Command	Description
`npm run dev`	Start development server
`npm run build`	Build for production
`npm run start`	Start production server

Quality checks

Command	Description
`npm run lint`	Run oxlint
`npm run lint:fix`	Fix oxlint findings
`npm run typecheck`	TypeScript type checking

Testing

Command	Description
`npm test`	Run Vitest unit tests (web)
`npm run test:e2e`	Run Playwright E2E tests
`npm run test:e2e-ui`	Playwright with UI mode
`npm run test:e2e-d`	Playwright debug mode

Editor setup

VS Code / Cursor

Recommended extensions:

Oxc / oxlint - Linting
Tailwind CSS IntelliSense - Tailwind autocompletion
TypeScript and JavaScript - Language support

The repository includes .vscode/settings.json for consistent configuration.

Code style

Styling

Use Tailwind CSS only (no SCSS/CSS files)
Use cn() from @/lib/utils for className composition
Follow semantic design tokens for colors

Components

Functional components with hooks
Strong TypeScript typing (avoid any)
Group imports: external → internal (@/) → relative

Import order

// 1. External libraries
import React, { useState, useEffect } from "react";
import { useRouter } from "next/navigation";

// 2. Internal aliases
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

// 3. Relative imports
import { MyComponent } from "./MyComponent";

Troubleshooting

Port 3000 already in use

Kill the process using the port:

lsof -ti:3000 | xargs kill -9

Clerk authentication fails

Verify environment variables:

Check .env.local exists in web/ directory
Ensure both NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY are set
Verify keys match your Clerk dashboard

API calls failing

Ensure api-events is running: curl http://localhost:4000/health
Check NEXT_PUBLIC_API_URL in .env.local
Verify your origin is in CORS_ORIGINS (defaults include localhost:3000 for local dev)

TypeScript errors

Run type checking to see all issues:

npm run typecheck

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Prerequisites

Quick start

Environment variables

Required variables

Optional variables

Feature flags

Running with backend

Access points

Development scripts

Core commands

Quality checks

Testing

Editor setup

VS Code / Cursor

Code style

Styling

Components

Import order

Troubleshooting

Next steps

Architecture

Testing

​Prerequisites

​Quick start

​Environment variables

​Required variables

​Optional variables

​Feature flags

​Running with backend

​Access points

​Development scripts

​Core commands

​Quality checks

​Testing

​Editor setup

​VS Code / Cursor

​Code style

​Styling

​Components

​Import order

​Troubleshooting

​Next steps

Architecture

Testing

Prerequisites

Quick start

Environment variables

Required variables

Optional variables

Feature flags

Running with backend

Access points

Development scripts

Core commands

Quality checks

Testing

Editor setup

VS Code / Cursor

Code style

Styling

Components

Import order

Troubleshooting

Next steps