Setup Guide

Local development setup for Brand Portal Frontend — the Nuxt 4 public-facing portal.

Repository: github.com/Collage-Inc/brand-portal

---

Prerequisites

Tool	Required version
Node.js	LTS (18+ recommended)
pnpm	Latest stable

Install pnpm via:

npm install -g pnpm

---

Clone Repository

git clone https://github.com/Collage-Inc/brand-portal.git
cd brand-portal

---

Install Dependencies

pnpm install

postinstall runs nuxt prepare and scripts/setup-pdfjs.cjs automatically.

---

Environment Variables

No .env.example is committed. Create .env manually with the variables below.

Minimum required variables to run locally:

Variable	Description
APP_NAME	App display name (e.g. Collage)
APP_ENV	Environment (development, staging, production)
BASE_URL	Frontend base URL (e.g. http://localhost:3000)
API_BASE_URL	Backend API base URL (e.g. http://localhost:8000/api)
BACKEND_URL	Backend root URL
ADMIN_FRONTEND_URL	Admin (collage-admin) URL
AUTH_SECRET	Random secret for HTTP-only session cookie signing
PUSHER_KEY	Pusher app key (real-time)
PUSHER_CLUSTER	Pusher cluster (e.g. mt1)
PUSHER_AUTH_ENDPOINT	Pusher auth endpoint
TYPESENSE_HOST	Typesense server host
TYPESENSE_PORT	Typesense port (default 8108)
TYPESENSE_PROTOCOL	http or https
TYPESENSE_API_KEY	Typesense search-only API key
AWS_ACCESS_KEY_ID	AWS key for S3
AWS_SECRET_ACCESS_KEY	AWS secret for S3
AWS_BUCKET	S3 bucket name
AWS_DEFAULT_REGION	AWS region (e.g. us-east-1)
AMPLITUDE_API_KEY	Amplitude project key (leave empty to disable)

Optional:

Variable	Default	Description
SECURE_AUTH_COOKIE	false	Set true in production (HTTPS only)
NUXT_PUBLIC_QUERY_STALE_TIME	300000	TanStack Query stale time in ms
SEARCH_KEY	—	Shared key for encrypting search state in URL
GOOGLE_AUTH_URL	—	Google OAuth redirect URL
TYPESENSE_CONNECTION_TIMEOUT	—	Typesense client timeout (ms)
ZIP_DOWNLOAD_URL	—	Zip download service URL

---

Start Dev Server

pnpm dev

Opens at http://localhost:3000 by default.

---

Other Commands

Command	Description
pnpm build	Production build
pnpm preview	Preview the production build locally
pnpm typecheck	Type-check all .ts and .vue files
pnpm lint	Run ESLint
pnpm lint:fix	Auto-fix ESLint issues
pnpm test	Run Vitest unit tests
pnpm test:coverage	Run tests with coverage report

---

Troubleshooting

Auth cookie not being set

Ensure AUTH_SECRET is set and SECURE_AUTH_COOKIE=false for local HTTP. The auth plugin load order is strict: Pinia → API client → Vue Query → Auth init — a missing secret breaks the chain silently.

Types missing after install

pnpm run postinstall

Regenerates .nuxt/ types and sets up PDF.js worker.

Real-time events not firing

Check PUSHER_KEY, PUSHER_CLUSTER, and PUSHER_AUTH_ENDPOINT. The auth endpoint must be reachable from the browser.