Development Guide¶
This guide describes the repository workflow for changing the Django backend, Next.js frontend, documentation, and deployment tooling.
Local Setup¶
- Fork or clone the repository and enter its root directory.
- Start Docker Desktop.
-
Run the supported setup command:
Use ./manage.sh setup --quick to skip optional prompts or ./manage.sh setup --skip-seed when catalog seed data is unnecessary.
4. Start both application servers with ./manage.sh start and check them with ./manage.sh status.
The setup script enables the shared git hooks, creates backend/venv, copies backend/.env.example when needed, installs backend and frontend dependencies, starts the PostgreSQL, Redis, and RabbitMQ development services, runs migrations, and can import seed data. It installs missing prerequisites with Homebrew (macOS). See Installation and Configuration for the expanded setup.
Build Commands¶
Commands that act on the frontend must be run from frontend/ unless the command starts with ./manage.sh.
| Command | Description |
|---|---|
./manage.sh start |
Start the local backend and frontend processes after checking services and dependencies. |
./manage.sh stop |
Stop the local application processes. |
./manage.sh restart |
Stop and start the local application processes. |
./manage.sh status |
Show backend, frontend, Docker-service, and URL status. |
./manage.sh ci-check |
Local approximation of CI: migrations, python manage.py test (the Django runner, not pytest), tsc --noEmit, Jest, ESLint. |
./manage.sh review [type] [base] |
CodeRabbit review of local changes (all, uncommitted, committed, plain, prompt). |
./manage.sh loadtest [suite] |
Run the k6 scripts in loadtests/ against the running backend (all, products, cart, upload). |
./manage.sh magic-links [email] |
List active magic-link codes for debugging authentication. |
./manage.sh createsuperuser |
Create a Django superuser. |
./manage.sh export-seed-data / import-seed-data / update-catalog |
Catalog export and import; see Seed Data. |
npm run dev |
Start the Next.js development server. |
npm run build |
Create the production Next.js build. |
npm run start |
Serve the production Next.js build. |
npm run lint |
Run ESLint. |
npm run check:env:staging |
Validate the frontend variables required by a staging image build. |
npm run generate:api-types |
Regenerate TypeScript API types from the Django OpenAPI schema. |
npm test |
Run Jest unit tests. |
npm run test:ci |
Run Jest in CI mode with coverage. |
npm run test:watch |
Run Jest in watch mode. |
npm run test:coverage |
Run Jest and write a coverage report. |
npm run test:e2e |
Run the Playwright projects. |
npm run test:e2e:ui |
Open Playwright's interactive runner. |
npm run test:e2e:headed |
Run Playwright with visible browsers. |
npm run storybook |
Start Storybook on port 6006. |
npm run build-storybook |
Generate the static Storybook site. |
npm run docs:typedoc |
Generate TypeDoc output. |
For backend development, activate backend/venv and run Django or pytest commands from backend/.
Code Style¶
- Frontend linting uses ESLint 9 with
frontend/eslint.config.mjs; runnpm run lintfromfrontend/. - TypeScript is checked with
npx tsc --noEmit. The pre-push hook and CI both run this check. - Backend CI runs flake8's error rules and reports complexity/style findings with a 127-character line limit. There is no repository-wide autoformatter configuration.
- Match nearby code and test conventions. Do not commit generated directories such as
frontend/.next/, coverage output, Playwright reports, or local virtual environments.
Branch Conventions¶
main is the default branch, while staging is the integration and automatic staging-deployment branch. Existing work uses descriptive prefixes such as feature/, fix/, test/, chore/, and dependabot/. Work on a feedback issue uses fix/feedback-<N>-<slug> or feature/feedback-<N>-<slug>; work on an internal todo uses fix/<todo-slug> or feature/<todo-slug> (see .claude/CLAUDE.md). Automation uses claude/dagplanning-<date>, claude/websitecheck-<date> and vrt/update-baselines-<timestamp>. Keep each branch focused on one change and open ordinary feature or fix pull requests against staging; promotion from staging to main is handled separately. Only staging and release/* may target main (enforced by enforce-pr-base.yml; a PR opened against main from any other branch is retargeted to staging by dependabot-retarget.yml).
PR Process¶
- Complete exactly one source reference in
.github/PULL_REQUEST_TEMPLATE.md:Feedback: Voorman/freezedesign-feedback#<N>for a feedback issue orRef: .planning/todos/pending/<slug>.mdfor an internal todo. - Explain what changed and why in the Wat / waarom section.
- Add reproducible staging verification steps as checkboxes under Verify on staging;
feedback-retest-comment.ymlcopies them to the feedback issue after the staging deploy. - Put anything only Ivar can do (secrets, accounts, decisions) under Voor Ivar;
voor-ivar-lijst.ymladds those lines to the pinned "Voor Ivar" issue on merge. - Run relevant backend, frontend, and E2E tests locally; the pre-push hook runs a backend subset, TypeScript, and Jest coverage.
- Open the pull request against
stagingunless it is the explicitstagingtomainpromotion. Merge is squash. - A PR built from the daily plan carries the line
Dagplanning: <date>and gets auto-merge fromdagbouw-bewaker.yml; never enable auto-merge on such a PR yourself (see GitHub Workflow). - Address CI and review findings without bypassing checks except when a documented incident procedure requires it.
- Where a todo or feedback issue stands (who is next, open PR, deployed where) is read-only in
python3 scripts/werkoverzicht.py(JSON or Dutch Markdown);scripts/werkbord.pyrenders the same as the Kanban page "Werkbord". Both only read (gh apiGET, read-only git).
API Contract Changes¶
When Django serializers, routes, or schemas change, regenerate the frontend contract before committing:
CI repeats this generation and fails when the committed TypeScript output has drifted. See the API Reference for authentication and endpoint conventions.