Setup

Prerequisites

Tool	Version
Bun	v1.3.11 or later (backend / frontend)
pnpm	v9 or later (Chrome extension)
Node.js	v22 or later (used when running orval)
Docker	For the local PostgreSQL
uv	For building this documentation

The make commands in the READMEs do not work

make setup / make dev / make docker-up in each repository's README refer to a Makefile that does not exist in this workspace. Use the commands below directly.

Steps

1. Clone the repositories

The layout assumes three repositories side by side under the workspace root.

mkdir -p design && cd design
git clone <backend repository URL> heineken-survey-design-backend
git clone <frontend repository URL> heineken-survey-design-frontend
git clone <extension repository URL> Lab-web-extension

2. Start PostgreSQL

The backend connects to PostgreSQL at 127.0.0.1:55432 (database survey_design).

docker run -d --name survey-design-db \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=survey_design \
  -p 55432:5432 postgres:16

3. Set up the backend

cd heineken-survey-design-backend
bun install
cp .env.example .env
bun run db:migrate    # apply migrations
bun run db:seed       # insert development seed data
bun run dev           # http://localhost:8787

Configure .env.

Name	Description	Example
`DATABASE_URL`	DB connection string	`postgres://postgres:postgres@127.0.0.1:55432/survey_design`
`SURVEY_ADMIN_EMAILS`	Administrator email addresses (comma separated)	`admin@example.com,foo@example.com`
`SURVEY_IMPORT_API_KEY`	API key for the import API. Key auth is disabled when unset	`local-import-key`

4. Set up the frontend

cd ../heineken-survey-design-frontend
bun install
cp .env.example .env
bun run dev           # http://localhost:3000

Configure .env. Google login requires an OAuth client.

Name	Description	Example
`NEXTAUTH_URL`	Base URL for next-auth	`http://localhost:3000`
`NEXTAUTH_SECRET`	Session encryption key	Output of `openssl rand -base64 32`
`GOOGLE_CLIENT_ID`	Google OAuth client ID	`xxxx.apps.googleusercontent.com`
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret	`GOCSPX-...`
`NEXT_PUBLIC_API_URL`	Base URL of the backend API	`http://localhost:8787`

Open http://localhost:3000 to verify.

5. Set up the Chrome extension

cd ../Lab-web-extension
pnpm install
pnpm dev

Enable Developer mode on Chrome's extensions page and load build/chrome-mv3-dev via "Load unpacked".

6. Set up the documentation

cd ../heineken-survey-design-docs
uv run mkdocs serve   # http://localhost:8000

Common Commands

backend

Command	Contents
`bun run dev`	Development server (`--hot`)
`bun test`	All tests
`bun test src/app.test.ts`	A single file
`bun test -t "test name"`	Filter by name
`bun run typecheck`	`tsc --noEmit`
`bun run export:openapi`	Write `openapi.json` (prerequisite for the frontend API client)
`bun run db:generate`	Generate migration SQL from schema changes
`bun run db:studio`	Launch the DB GUI

frontend

Command	Contents
`bun run dev`	Development server
`bun run test`	Vitest
`bun run test -- path/to/file.test.tsx`	A single file
`bun run lint` / `bun run lint:fix`	ESLint
`bun run format` / `bun run format:write`	Prettier
`bun run storybook`	Storybook (`http://localhost:6006`)
`bun run generate:api`	Regenerate the API client
`bun run new:component` / `bun run new:common`	Generate component scaffolding

Chrome extension

Command	Contents
`pnpm dev`	Development build
`pnpm build`	Production build
`pnpm test`	Vitest

Regenerating the API Client

After changing a backend API, propagate it to the frontend in this order.

cd heineken-survey-design-backend && bun run export:openapi
cd ../heineken-survey-design-frontend && bun run generate:api

lib/api/generated.ts and lib/api/model/ are rebuilt every time and must not be edited by hand.

Common Errors

`make: *** No rule to make target`

Cause: The Makefile referenced in the README does not exist in the workspace.

Solution: Use the bun run / pnpm commands above directly.

The backend cannot connect to the database

Cause: PostgreSQL is not running, or DATABASE_URL points at the wrong port.

Solution:

docker ps | grep survey-design-db     # check that it is running
cat .env | grep DATABASE_URL          # check that it points at 55432

Frontend API calls return 401

Cause: Google login has not been completed, or the user headers are not reaching the backend.

Solution: Log in again from /login. The backend requires both x-user-email and x-user-name.

`bun run generate:api` fails

Cause: The backend's openapi.json is out of date, or the Node.js version orval needs is missing.