> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Setup

> Set up local development for the Soundcheck web app

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

## Prerequisites

* Node.js 20+ (recommended: use [nvm](https://github.com/nvm-sh/nvm))
* npm, yarn, pnpm, or bun
* Git

***

## Quick start

**1. Navigate to web directory**

```bash theme={null}
cd web
```

**2. Install dependencies**

```bash theme={null}
npm install
```

**3. Set up environment variables**

```bash theme={null}
cp .env.example .env.local
```

Edit `.env.local` with your configuration:

```env theme={null}
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
```

**4. Start the development server**

```bash theme={null}
npm run dev
```

**5. Open in browser**

Navigate to [http://localhost:3000](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:

1. Session override from the header beaker menu (this browser, persisted as `sc.dev.feature-flag-overrides`)
2. `NEXT_PUBLIC_FF_*` environment variables
3. PostHog
4. 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:

**1. Start shared infrastructure and API**

In a separate terminal:

```bash theme={null}
npm run dev:infra
cd api-events && npm run db:migrate && npm run dev:emulator
```

**2. Start the web app**

```bash theme={null}
cd web
npm run dev:emulator
```

### Access points

| Service | URL |
| - | - |
| Web App | [http://localhost:3000](http://localhost:3000) |
| api-events | [http://localhost:4000](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

```tsx theme={null}
// 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

> [accordion] Port 3000 already in use
>
> Kill the process using the port:
>
> ```bash theme={null}
> lsof -ti:3000 | xargs kill -9
> ```

> [accordion] Clerk authentication fails
>
> Verify environment variables:
>
> 1. Check `.env.local` exists in `web/` directory
> 2. Ensure both `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` are set
> 3. Verify keys match your Clerk dashboard

> [accordion] API calls failing
>
> 1. Ensure api-events is running: `curl http://localhost:4000/health`
> 2. Check `NEXT_PUBLIC_API_URL` in `.env.local`
> 3. Verify your origin is in `CORS_ORIGINS` (defaults include `localhost:3000` for local dev)

> [accordion] TypeScript errors
>
> Run type checking to see all issues:
>
> ```bash theme={null}
> npm run typecheck
> ```

***

## Next steps

> [card] [Architecture](https://docs.soundchecklive.io/engineering/frontend/architecture.md)
>
> Understand the app structure

> [card] [Testing](https://docs.soundchecklive.io/engineering/frontend/testing.md)
>
> Learn about testing strategies


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.