This document covers the Makefile-based build orchestration system that manages the development lifecycle for both the reference implementation (API) and the documentation site. The Makefile serves as the central command interface, abstracting complex multi-step workflows into simple, memorable targets.
This page documents:
For details about the CI/CD pipeline implementations, see CI/CD Pipelines. For running the API tests themselves, see Running API Tests. For local development of the reference implementation, see Running Locally.
The build system is organized around a single Makefile at the repository root that orchestrates all build, test, and development operations across the monorepo. It provides a consistent interface regardless of the underlying package managers (npm for API, bun for documentation) or frameworks used.
The Makefile defines phony targets organized into four functional categories:
| Category | Purpose | Example Targets |
|---|---|---|
| Reference Implementation - Setup | Initial project configuration | reference-implementation-setup, reference-implementation-setup-db-generate |
| Reference Implementation - Run | Development server execution | reference-implementation-run-for-postman |
| Reference Implementation - Tests | Test execution | reference-implementation-test-with-postman |
| Documentation | Doc site build and preview | documentation-setup, documentation-build, documentation-dev |
| Cleaning | Artifact and process cleanup | running-processes-clean, non-default-files-clean |
All targets are declared as .PHONY to ensure they always execute regardless of file timestamps Makefile1-16
The help target provides self-documentation:
This displays all available commands grouped by category Makefile18-32
Sources: Makefile1-32
Diagram: Reference Implementation Build and Run Workflow
Sources: Makefile34-58
The main setup target reference-implementation-setup Makefile46-52 executes three sub-tasks in sequence:
Executes npm i in the apps/api directory to install all Node.js dependencies specified in package.json Makefile37-38
Runs npm run prepare which invokes the Nitro framework's preparation step Makefile40-41 This generates internal build artifacts needed for the server.
Executes npm run db:generate in the apps/api/server directory Makefile43-44 This runs prisma generate to:
node_modules/@prisma/clientapps/api/prisma/dev.dbEach step includes colored console output to indicate completion Makefile48-52
Sources: Makefile34-52
This target starts the Nitro development server with a hardcoded JWT secret for testing purposes Makefile57-58:
⚠️ Warning: This configuration is explicitly marked as "not production ready" in the Makefile comments Makefile57 due to the exposed JWT secret.
Sources: Makefile54-58
Diagram: Test Execution with Automatic Server Lifecycle Management
Sources: Makefile60-77 api/run-api-tests.sh1-20
This target implements a sophisticated server lifecycle management pattern Makefile66-77:
Launches the dev server with the test JWT secret as a background process:
The process ID is captured in SERVER_PID=$$! Makefile68-69
Registers a cleanup handler to kill the server on exit:
This ensures the server is terminated even if the tests fail Makefile70
Sleeps for 0.3 seconds to allow server startup, then verifies the server process is still alive:
If the server has crashed, exits with code 4 Makefile71-72
Invokes the test runner with localhost configuration:
This sets DELAY_REQUEST=50 and APIURL=http://localhost:3000/api Makefile64 then calls the test script.
The test result determines the output:
running-processes-clean, prints green "TESTS OK", exits 0 Makefile73-75running-processes-clean, prints red "TESTS FAILED", exits 1 Makefile75-77Sources: Makefile60-77
The api/run-api-tests.sh script wraps Newman execution with environment variable defaults:
| Variable | Default | Purpose |
|---|---|---|
APIURL | https://api.realworld.io/api | Base URL for API requests |
USERNAME | u{timestamp} | Unique username for test user |
EMAIL | {username}@mail.com | Email derived from username |
PASSWORD | password | Test user password |
DELAY_REQUEST | 500 | Milliseconds between requests |
The script uses bun x newman to execute the Postman collection api/run-api-tests.sh13-19:
Sources: api/run-api-tests.sh1-20
Diagram: Documentation Site Build Pipeline
Sources: Makefile93-112
The documentation workflow uses bun as the package manager and runtime:
Installs dependencies in apps/documentation using bun install Makefile96-97
Local development (localhost only):
Runs bun run dev which starts the Astro development server with hot module replacement Makefile99-100
Network-accessible development:
Adds the --host flag to expose the dev server on the network interface Makefile102-103
Executes bun run build which generates static HTML/CSS/JS to the apps/documentation/dist/ directory Makefile105-106
Runs bun run preview to serve the built static site locally for verification before deployment Makefile108-109
Removes build artifacts Makefile111-112:
.astro/ - Astro cache directorydist/ - Build outputnode_modules/ - DependenciesSources: Makefile93-112
This target implements a robust process cleanup mechanism Makefile82-87:
Why this is necessary: Killing the parent shell process doesn't always terminate the Nitro dev server child process. This command:
SIGKILL (-9)The || true ensures the make target succeeds even if no processes are found Makefile87
Sources: Makefile79-87
Removes generated files to restore the repository to a clean state Makefile89-91:
apps/api/node_modules/ - npm dependencies including Prisma clientapps/api/prisma/dev.db - SQLite development databaseNote: There's a typo in the Makefile path Makefile91: appd/api/prisma/dev.db should be apps/api/prisma/dev.db. This target may not function correctly.
Sources: Makefile89-91
Diagram: Make Target Relationships
This diagram shows the dependency relationships between make targets. Solid arrows indicate explicit dependencies within a target's execution. Dotted arrows indicate logical prerequisites that aren't enforced by the Makefile.
Sources: Makefile1-113
While the GitHub Actions workflow files aren't included in the provided sources, the Makefile serves as the integration point for continuous integration pipelines. Based on the high-level architecture diagrams, the following workflows exist:
| Workflow | Purpose | Likely Make Commands |
|---|---|---|
api.yaml | API test execution | reference-implementation-setup, reference-implementation-test-with-postman |
api-testing-playwright.yaml | E2E test execution | Similar setup, different test runner |
codeql.yml | Security scanning | No direct Makefile integration |
chromatic.yml | Visual regression testing | No direct Makefile integration |
The Makefile's abstraction of setup and testing into simple targets makes it easy for CI systems to execute the same commands that developers run locally, ensuring consistency between development and CI environments.
For detailed CI/CD pipeline documentation, see CI/CD Pipelines.
Sources: Based on high-level architecture diagrams
Sources: Makefile1-113
The Makefile-based build system provides:
make helpThe system successfully abstracts the complexity of managing a monorepo containing a Nitro-based API and an Astro-based documentation site, making it accessible to contributors regardless of their familiarity with the underlying technologies.
Sources: Makefile1-113 api/run-api-tests.sh1-20
Refresh this wiki