| 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 developmentACCOUNT_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
