project-setup

name	project-setup
description	Guide first-time setup and launching of the multi-org-analytics app. Use when a new developer needs to set up the project, install dependencies, configure the database, or run the dev server.

Project Setup

Prerequisites

• Node.js (LTS recommended)
• npm

First-Time Setup

Walk the user through these steps in order:

1. Install dependencies

cd web
npm install

2. Configure environment

cp .env.example .env

Then set values in .env:

• DATABASE_URL -- defaults to "file:./dev.db" (local SQLite), usually fine for development
• ACCOUNT_ENCRYPTION_SECRET -- set to a long random string (used for AES-256-GCM encryption of API keys)

Generate a secret quickly:

openssl rand -base64 32

3. Set up the database

npx prisma generate
npx prisma migrate dev

This creates a local SQLite database at web/dev.db and generates the Prisma Client.

4. Start the dev server

npm run dev

The app runs at http://localhost:3000.

Common Scripts

Command	Purpose
npm run dev	Start development server
npm run build	Production build
npm run start	Start production server
npm run lint	Run ESLint
npm run typecheck	Type-check without emitting
npm run test	Run Vitest unit tests
npm run test:watch	Vitest in watch mode
npm run test:e2e	Run Playwright e2e tests

Tech Stack

• Framework: Next.js (App Router)
• Language: TypeScript
• Database: SQLite via Prisma ORM (libSQL adapter)
• Styling: Tailwind CSS v4
• Testing: Vitest + Playwright

Troubleshooting

• Prisma Client errors after schema changes: Re-run npx prisma generate
• Database out of sync: Run npx prisma migrate dev to apply pending migrations
• Port 3000 in use: Kill the existing process or set PORT env var