# Local setup — step by step

A complete, from-scratch guide to running this demo on your machine. No database, no external
services, no accounts. It's a static demo: mock data ships in code and every feature works.

## 1. Prerequisites

| Tool | Version | Check |
|---|---|---|
| Node.js | ≥ 20 (tested on 24) | `node -v` |
| pnpm | ≥ 8 (tested on 11) | `pnpm -v` |
| Git | any | `git --version` |

Don't have pnpm? `npm install -g pnpm` (or `corepack enable`).

## 2. Install

```bash
cd message-inbox-web-frontend-sdk
pnpm install
```

This installs the workspace (the SDK in `packages/` + the app in `apps/web`). First install pulls
Next.js/React/Tailwind — on a slow connection it can take a few minutes.

> **If install or `pnpm dev` fails with a corepack error** (e.g. "Server answered with HTTP 404 …
> pnpm-X.Y.Z.tgz"): this repo intentionally has **no** `packageManager` pin, so just use your local
> pnpm. If your shell forces corepack, run `corepack disable` once, then `pnpm install` again.
>
> **If install times out on a large tarball** (slow network), retry with a longer timeout:
> `pnpm install --fetch-timeout 2400000 --fetch-retries 10 --network-concurrency 2`.

## 3. Run

```bash
pnpm dev
```

Open **http://localhost:4300**. You land in `#general` with a full mock workspace.

To run only the web app: `pnpm --filter @lynkd/web dev`.
To change the port: edit `dev`/`start` scripts in `apps/web/package.json` (`next dev -p 4300`).

## 4. Configure (optional)

Everything works with defaults. To customize, copy the example env and edit:

```bash
cp apps/web/.env.example apps/web/.env.local
```

- **Feature flags** — `NEXT_PUBLIC_FEATURE_*` (all default on). e.g. `NEXT_PUBLIC_FEATURE_SUPPORT=false`.
- **Theme** — `NEXT_PUBLIC_THEME_MODE`, `NEXT_PUBLIC_THEME_ACCENT`, `NEXT_PUBLIC_THEME_RADIUS_CARD`, …
- **Branding** — `NEXT_PUBLIC_BRAND_NAME`.

Restart `pnpm dev` after changing env. Full references: [`FEATURE_FLAGS.md`](FEATURE_FLAGS.md),
[`THEMING.md`](THEMING.md).

## 5. Two-minute demo tour

1. **Send** a message in `#general` (rich composer: select text → **Bold**/Italic/Code; ⏎ to send).
2. **Hover** a message → react 🎉, reply in thread, pin, save, or the **⋯** menu.
3. **⌘K / Ctrl+K** → search channels, people, messages, tickets.
4. **Add channels** (sidebar) → create one; it appears and opens instantly.
5. **Inbox** → work the queue (done / snooze / archive).
6. **Support** → open **TCK-1042**, reply, **Resolve** (watch the list + stats update live).
7. **Theme** → top-right ☀️/🌙, or the **Appearance** panel (accent, radius, gradient, System mode).
8. **Start a huddle** (video icon) → floating call bar with working mute/video/share toggles.
9. Resize the window narrow — the layout stays responsive (sidebar → drawer, support → single pane).

## 6. Common tasks

| Task | Where |
|---|---|
| Add/seed mock data | `apps/web/lib/mock/data.ts` |
| Add a BFF endpoint | `apps/web/app/api/bff/<path>/route.ts` (+ `store` method + `BffClient` method) |
| Add a feature flag | `packages/messaging-inbox-sdk/src/config.ts` |
| Change default theme | `packages/messaging-inbox-sdk/src/config.ts` (`darkTokens`/`lightTokens`) |
| Add a page | `apps/web/app/(app)/<route>/page.tsx` |

## 7. Build for production

```bash
pnpm build
pnpm start        # serves the built app on :4300
```

> The demo is not production-hardened, and the Next.js version is pinned for the demo (has a known
> CVE). Bump Next and wire a real backend (see [`IIOS_INTEGRATION.md`](IIOS_INTEGRATION.md)) before
> deploying.

## 8. Troubleshooting

| Symptom | Fix |
|---|---|
| corepack 404 on pnpm | `corepack disable`, re-run (no pin in this repo) |
| install times out | add `--fetch-timeout 2400000 --network-concurrency 2` |
| port 4300 in use | change the port in `apps/web/package.json` scripts |
| `store.X is not a function` after editing the store | bump `__lynkdStore_vN` in `lib/mock/store.ts` or restart `pnpm dev` (HMR singleton) |
| styles look unstyled | ensure `pnpm dev` compiled Tailwind (check the terminal); hard-reload |
| sent messages vanished | expected on server restart — the mock store is in-memory |