This page provides instructions for setting up and running the RealWorld reference implementation on your local development machine. It covers the initial setup process, environment configuration, development server execution, and local testing workflows.
For information about the underlying technology stack, see Technology Stack. For details about the database schema and Prisma configuration, see Database Layer & Prisma. For comprehensive testing procedures including CI/CD workflows, see Testing Infrastructure.
Before running the reference implementation locally, ensure you have the following installed:
| Tool | Purpose | Minimum Version |
|---|---|---|
| Node.js | Runtime environment | 18.18+ |
| npm | Package manager | Bundled with Node.js |
| bun | Test runner for Newman | Latest |
The implementation uses SQLite as the development database, which requires no separate installation.
Sources: apps/api/package.json1-26
The setup process consists of three sequential phases that prepare the development environment. These phases can be executed via Makefile targets or directly using npm commands.
Sources: Makefile37-52 apps/api/package.json3-10
The Makefile provides a high-level orchestration interface that executes all setup phases in sequence.
Run the complete setup process:
This target executes three sub-targets in order:
reference-implementation-setup-install-dependencies - Runs npm i in apps/api/reference-implementation-setup-nitro-prepare - Runs npm run preparereference-implementation-setup-db-generate - Runs npm run db:generate in apps/api/server/Each phase outputs a colored success message upon completion.
Sources: Makefile46-52
You can also run setup phases individually for troubleshooting:
Sources: Makefile37-44
Alternatively, you can run setup commands directly without the Makefile:
Sources: apps/api/package.json3-10
The API requires a JWT_SECRET environment variable for token generation and validation. This secret is used by the authentication system to sign and verify JSON Web Tokens.
Development Secret (Not for Production):
⚠️ Warning: The Makefile includes a hardcoded development secret. This is clearly marked as "not production ready" and should never be used in production deployments.
Sources: Makefile57-58 Makefile67-68
You can set environment variables in three ways:
Inline with command:
Export in shell:
Using Makefile target (uses development secret automatically):
Sources: Makefile57-58
Sources: Makefile57-58 apps/api/package.json5
This command:
JWT_SECRET environment variablenpm run dev in apps/api/Sources: Makefile57-58
The dev script executes nitro dev, which:
Sources: apps/api/package.json5
Once running, the API is accessible at:
http://localhost:3000http://localhost:3000/api/*All routes are prefixed with /api as defined by the Nitro route structure in server/routes/api/.
Sources: Makefile66-77 api/run-api-tests.sh1-20
Execute the complete test suite against a locally-started server:
This target:
JWT_SECRET setkill -0 checkrun-api-tests.shrunning-processes-cleanSources: Makefile66-77
If you have the server running in a separate terminal:
This sets DELAY_REQUEST=50 and APIURL=http://localhost:3000/api, then runs the test script without starting/stopping the server.
Sources: Makefile63-64
Run tests directly using the shell script:
Sources: api/run-api-tests.sh6-19
| Variable | Default | Purpose |
|---|---|---|
APIURL | https://api.realworld.io/api | API base URL to test against |
USERNAME | u{timestamp} | Username for test account creation |
EMAIL | {USERNAME}@mail.com | Email for test account |
PASSWORD | password | Password for test account |
DELAY_REQUEST | 500 (or 50 when local) | Milliseconds between requests |
Sources: api/run-api-tests.sh6-11 Makefile64
The following npm scripts are available in apps/api/package.json:
| Script | Command | Purpose |
|---|---|---|
dev | nitro dev | Start development server with hot reload |
build | nitro build | Build production bundle to .output/ |
preview | node .output/server/index.mjs | Preview production build locally |
start | node .output/server/index.mjs | Start production server |
prepare | nitro prepare | Generate Nitro type definitions |
db:generate | npx prisma generate | Generate Prisma Client from schema |
db:seed | npx prisma db seed | Seed database with sample data |
Sources: apps/api/package.json3-10
The Prisma Client must be generated before running the application. This creates type-safe database access code in node_modules/@prisma/client.
This command:
prisma/schema.prismadev.db SQLite database if it doesn't existSources: apps/api/package.json9 Makefile43-44
Populate the database with sample data:
The seed script is defined at prisma/seed.ts and runs via ts-node --transpile-only.
Sources: apps/api/package.json10-13
The SQLite database file is created at:
apps/api/prisma/dev.db
This file is generated automatically during Prisma Client generation and persists between server restarts.
Sources: Makefile91
The Makefile includes a helper target to kill all running Nitro development servers:
This command:
ps a -A -o pid,cmd{pwd}/apps/api/node_modules/.bin/nitro devkill -9This is necessary because simply killing the parent Makefile process doesn't always terminate all child processes.
Sources: Makefile82-87
Remove all generated files and return to a clean state:
This deletes:
apps/api/node_modules/ (including Prisma Client at node_modules/@prisma/client)apps/api/prisma/dev.db (SQLite database)After running this, you must re-run make reference-implementation-setup before starting the server.
Sources: Makefile89-91
The development server runs on port 3000 by default. This is configured by Nitro's default settings.
To verify the server is running:
The API routes are prefixed with /api, so all endpoints from the OpenAPI specification are available at http://localhost:3000/api/{endpoint}.
Sources: Makefile18-32
After setup, the following directory structure exists:
apps/api/
├── node_modules/ # Dependencies (including @prisma/client)
├── prisma/
│ ├── schema.prisma # Database schema definition
│ ├── dev.db # SQLite database file (generated)
│ └── seed.ts # Database seeding script
├── server/
│ └── routes/api/ # API route handlers
├── .output/ # Production build output (after npm run build)
└── package.json # Package configuration and scripts
The .output/ directory is only created after running npm run build and contains the production bundle.
Sources: Makefile89-91 apps/api/package.json1-26
Refresh this wiki