Setup Guide

Local development setup for collage-admin — the Nuxt 4 DAM frontend.

Repository: github.com/Collage-Inc/collage-admin

---

Prerequisites

Tool	Required version
Node.js	^22.12.0 (LTS recommended)
pnpm	>=9.0.0

Install Node via nvm or fnm and pnpm via:

npm install -g pnpm

---

Clone Repository

git clone https://github.com/Collage-Inc/collage-admin.git
cd collage-admin

---

Install Dependencies

pnpm install

postinstall runs nuxt prepare automatically, generating .nuxt/ types.

---

Environment Variables

Copy the example file and fill in the required values:

cp .env.example .env

Minimum required variables to run locally:

Variable	Description
APP_NAME	App display name (e.g. Collage DAM)
APP_ENV	Environment name (development, staging, production)
API_BASE_URL	Backend API base URL (e.g. http://localhost:8000/api)
BACKEND_URL	Backend root URL
BASE_URL	Frontend base URL (e.g. http://localhost:3000)
DAM_FRONTEND_URL	DAM frontend URL
PUSHER_KEY	Pusher app key (for real-time WebSocket)
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 uploads
AWS_SECRET_ACCESS_KEY	AWS secret for S3 uploads
AWS_BUCKET	S3 bucket name
AWS_DEFAULT_REGION	AWS region (e.g. us-east-1)
STRIPE_PUBLISHABLE_KEY	Stripe publishable key (front-end checkout)
STRIPE_SECRET_KEY	Stripe secret key (server-side billing)
AMPLITUDE_API_KEY	Amplitude project key (set empty to disable tracking)

Optional:

Variable	Default	Description
NUXT_PUBLIC_QUERY_STALE_TIME	300000	TanStack Query stale time in ms (5 min)

Full variable reference is in .env.example at the repo root.

---

Start Dev Server

pnpm dev

Opens at http://localhost:3000 by default. Hot module replacement is enabled.

---

Other Commands

Command	Description
pnpm build	Production build (nuxt 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 clean	Remove .nuxt, .output, and Vite cache

---

Troubleshooting

Types missing or stale after install

pnpm run postinstall

Runs nuxt prepare to regenerate .nuxt/ types without a full reinstall.

Port already in use

Override the port via .env:

PORT=3001

Module not found after switching branches

pnpm clean && pnpm install