# Vercel deployment — frontend environment variables

Use this guide when deploying `saleshub-frontend` to [Vercel](https://vercel.com).

## Project settings

| Setting | Value |
|--------|--------|
| **Root Directory** | `saleshub-frontend` |
| **Framework Preset** | Next.js |
| **Build Command** | `npm run build` (default) |
| **Install Command** | `npm install` or `pnpm install` |
| **Output Directory** | (default — Next.js) |

The app runs on port **3001** locally (`npm run dev`); Vercel assigns the production URL automatically.

## Environment variables (Vercel dashboard)

Open **Project → Settings → Environment Variables** and add the variables below.
Apply them to **Production**, **Preview**, and **Development** as needed.

### Required

| Variable | Example (production) | Notes |
|----------|----------------------|--------|
| `NEXT_PUBLIC_API_URL` | `https://api.yourdomain.com/v1` | Public. Backend REST base URL **including** `/v1`. **No trailing slash.** Must be reachable from the browser (CORS configured on the API). |
| `NEXTAUTH_URL` | `https://your-app.vercel.app/api/auth` | Server-only at build/runtime for NextAuth. **Must end with `/api/auth`** (matches `NEXT_AUTH_BASE_PATH` in code). Use your custom domain if you have one: `https://crm.yourdomain.com/api/auth`. |
| `NEXTAUTH_SECRET` | *(generate — see below)* | Server-only. Used to sign session tokens. **Never commit** real values. |

Generate a secret:

```bash
openssl rand -base64 32
```

### Recommended

| Variable | Example | Notes |
|----------|---------|--------|
| `NEXTAUTH_SESSION_MAX_AGE` | `28800` | Session length in seconds (default 8h). Keep aligned with backend `JWT_ACCESS_EXPIRES_IN`. |

### Optional (real-time notifications)

Only set these if Socket.IO is enabled on the backend and proxied correctly.

| Variable | Example | Notes |
|----------|---------|--------|
| `NEXT_PUBLIC_SOCKET_URL` | `https://api.yourdomain.com` | WebSocket **server origin** (no `/v1`). Defaults to the origin of `NEXT_PUBLIC_API_URL` if unset. |
| `NEXT_PUBLIC_SOCKET_PATH` | `/socket.io` | Must match backend `SOCKET_IO_PATH`. |

## Example: Production on Vercel + API elsewhere

```env
NEXT_PUBLIC_API_URL=https://api.yourdomain.com/v1
NEXTAUTH_URL=https://crm.yourdomain.com/api/auth
NEXTAUTH_SECRET=<openssl-generated-secret>
NEXTAUTH_SESSION_MAX_AGE=28800
NEXT_PUBLIC_SOCKET_URL=https://api.yourdomain.com
```

## Example: Preview deployments

For preview URLs (`*.vercel.app`), set **Preview**-scoped variables:

```env
NEXT_PUBLIC_API_URL=https://staging-api.yourdomain.com/v1
NEXTAUTH_URL=https://your-app-git-branch-team.vercel.app/api/auth
NEXTAUTH_SECRET=<same-or-preview-specific-secret>
```

**Important:** `NEXTAUTH_URL` must match the **exact** preview URL host for that deployment, or login callbacks will fail. Consider a stable staging domain instead of per-branch preview URLs if auth is hard to automate.

## Local development

```bash
cd saleshub-frontend
cp .env.example .env.local
# Edit .env.local with your values
npm run dev
```

Default local values:

```env
NEXT_PUBLIC_API_URL=http://localhost:3002/v1
NEXTAUTH_URL=http://localhost:3001/api/auth
NEXTAUTH_SECRET=<local-dev-secret>
NEXTAUTH_SESSION_MAX_AGE=28800
```

## Checklist after deploy

1. **API CORS** — Backend allows your Vercel origin (and custom domain).
2. **`NEXTAUTH_URL`** — Matches live site URL + `/api/auth`.
3. **`NEXT_PUBLIC_API_URL`** — Browser can reach the API over HTTPS.
4. **Login** — Sign in works; session persists across refresh.
5. **Sockets** (if used) — Notifications connect; set `NEXT_PUBLIC_SOCKET_URL` if REST and WS hosts differ.

## Do not set on Vercel (frontend)

These belong on the **backend** only, not in the Next.js project:

- `DATABASE_URL`
- `JWT_SECRET` / backend auth secrets
- Stripe keys, email provider keys, etc.

## Reference

| File | Purpose |
|------|---------|
| `.env.example` | Template for local `.env.local` and variable names |
| `src/api/client.ts` | `NEXT_PUBLIC_*` API and socket URLs |
| `src/lib/auth.ts` | `NEXTAUTH_SECRET`, `NEXTAUTH_SESSION_MAX_AGE` |
| `src/lib/next-auth-path.ts` | Auth route base path (`/api/auth`) |