Setup & Installation Process

Relevant source files

• Makefile
• api/run-api-tests.sh
• apps/api/package-lock.json
• apps/api/package.json
• apps/api/prisma/dev.db

This document describes the multi-phase setup process required to initialize both the reference implementation API and the documentation site. The setup includes dependency installation, framework preparation, database client generation, and optional data seeding.

For information about running the API locally after setup, see Running Locally. For details on available Makefile commands, see Makefile Commands.

---

Overview

The RealWorld repository contains two primary applications that require separate setup procedures:

Application	Location	Setup Target	Purpose
Reference Implementation	apps/api/	reference-implementation-setup	Node.js API server with Nitro + Prisma
Documentation Site	apps/documentation/	documentation-setup	Astro + Starlight static site generator

Both setups are orchestrated through the root Makefile1-113 using declarative targets that abstract multi-step initialization processes.

---

Prerequisites

The following tools must be installed before beginning setup:

• Node.js (>=18.18) - Required for the Nitro framework and Prisma
• npm - Node package manager for reference implementation dependencies
• bun - Fast JavaScript runtime used for documentation site and test execution
• make - Build automation tool for executing Makefile targets

---

Reference Implementation Setup

The reference implementation requires a three-phase setup process that prepares the Nitro framework, installs dependencies, and generates the Prisma database client.

Setup Flow Diagram

Sources: Makefile46-52 apps/api/package.json3-10

Phase 1: Dependency Installation

The first phase installs all npm dependencies specified in package.json.

Makefile Target:

make reference-implementation-setup-install-dependencies

Implementation: Makefile37-38

Installed Dependencies:

Package	Type	Purpose
@prisma/client	production	Generated database client for type-safe queries
bcryptjs	production	Password hashing for user authentication
slugify	production	Article slug generation
nitropack	development	Server framework and build tool
prisma	development	ORM and database migration CLI
jsonwebtoken	development	JWT token generation and validation
@ngneat/falso	development	Fake data generation for seeding

Output: Creates apps/api/node_modules/ directory with all dependencies.

Sources: Makefile37-38 apps/api/package.json15-25

Phase 2: Nitro Framework Preparation

The second phase initializes the Nitro framework's build cache and development environment.

Makefile Target:

make reference-implementation-setup-nitro-prepare

Implementation: Makefile40-41

Executed Script: apps/api/package.json6 - "prepare": "nitro prepare"

Purpose: The nitro prepare command:

• Creates the .nitro/ build cache directory
• Generates TypeScript type definitions for Nitro route handlers
• Pre-compiles framework internals for faster startup
• Configures the development server environment

Output: Creates apps/api/.nitro/ directory with framework cache files.

Sources: Makefile40-41 apps/api/package.json6

Phase 3: Prisma Client Generation

The third phase generates the Prisma client from the database schema and creates the SQLite database file.

Makefile Target:

make reference-implementation-setup-db-generate

Implementation: Makefile43-44

Executed Script: apps/api/package.json9 - "db:generate": "npx prisma generate"

Process Flow:

Generated Artifacts:

Path	Description
node_modules/@prisma/client/	Type-safe database client with TypeScript definitions
node_modules/.prisma/client/	Generated runtime code for database access
prisma/dev.db	SQLite database file (created if doesn't exist)

Sources: Makefile43-44 apps/api/package.json9

Complete Setup Command

All three phases can be executed sequentially with a single command:

make reference-implementation-setup

Implementation: Makefile46-52

This target executes all three phases in order and prints colored status messages:

• INSTALLED DEPENDENCIES after Phase 1
• PREPARED NITRO after Phase 2
• GENERATED PRISMA after Phase 3

Sources: Makefile46-52

Optional: Database Seeding

After setup, the database can be populated with sample data using the seed script:

npm run db:seed

Implementation: apps/api/package.json10 - "db:seed": "npx prisma db seed"

Seed Configuration: apps/api/package.json12-13 - Executes prisma/seed.ts using ts-node --transpile-only

The seed script uses @ngneat/falso to generate realistic fake data for users, articles, comments, and tags.

Sources: apps/api/package.json10-13

---

Documentation Site Setup

The documentation site requires a simpler single-phase setup using bun.

Makefile Target:

make documentation-setup

Implementation: Makefile96-97

Process:

Installed Dependencies:

• astro - Static site generator
• @astrojs/starlight - Documentation theme
• @astrojs/tailwind - TailwindCSS integration
• @astrojs/check - TypeScript validation

Output: Creates apps/documentation/node_modules/ directory.

Sources: Makefile96-97

---

Environment Variables

The reference implementation requires specific environment variables for operation. These are typically set during testing but can be configured for development.

Required Variables

Variable	Purpose	Example Value	Used By
JWT_SECRET	Secret key for signing JWT tokens	dxLmhnE0pRY2+vUlu+i5Pxh8LTxLBTgBWdp82W74mMs=	Authentication middleware

Test Environment Variables

When running API tests, additional variables configure the test environment:

Variable	Purpose	Default	Source
APIURL	API endpoint URL	https://api.realworld.io/api	api/run-api-tests.sh6
USERNAME	Test user username	u{timestamp}	api/run-api-tests.sh7
EMAIL	Test user email	{USERNAME}@mail.com	api/run-api-tests.sh8
PASSWORD	Test user password	password	api/run-api-tests.sh9
DELAY_REQUEST	Delay between test requests (ms)	500	api/run-api-tests.sh11

Example Test Execution: Makefile58 sets JWT_SECRET when running the development server for testing.

Sources: Makefile58 api/run-api-tests.sh6-11

---

Generated File Structure

After successful setup, the following directory structure is created:

Sources: Makefile37-97

---

Verification Steps

After completing setup, verify the installation:

Reference Implementation Verification

1. Check dependencies installed:

   Should contain generated Prisma client files.

2. Check Nitro prepared:

   Should contain build cache directory.

3. Check database created:

   Should exist as SQLite database file.

4. Start development server:

   Should start Nitro server on http://localhost:3000

Documentation Verification

1. Check dependencies installed:

   Should contain Astro package.

2. Start development server:

   Should start Astro dev server on http://localhost:4321

Sources: apps/api/package.json5 Makefile99-100

---

Cleaning Generated Files

To reset the environment and remove all generated files:

Reference Implementation Cleanup

make non-default-files-clean

Implementation: Makefile89-91

Removes:

• apps/api/node_modules/ - All npm dependencies
• apps/api/prisma/dev.db - SQLite database file

Documentation Cleanup

make documentation-clean

Implementation: Makefile111-112

Removes:

• apps/documentation/.astro/ - Astro build cache
• apps/documentation/dist/ - Built static site
• apps/documentation/node_modules/ - All dependencies

Sources: Makefile89-112

---

Troubleshooting

Common Setup Issues

Issue	Cause	Solution
npm i fails	Node version < 18.18	Upgrade Node.js to >= 18.18
prisma generate fails	Corrupted schema cache	Run npx prisma format to validate schema
nitro prepare fails	Permission issues	Check write permissions in apps/api/ directory
Port 3000 already in use	Another process using port	Kill existing process or set PORT environment variable

Reset and Retry

If setup fails at any phase:

1. Clean all generated files: make non-default-files-clean
2. Delete node_modules: rm -rf apps/api/node_modules
3. Re-run setup: make reference-implementation-setup

Sources: Makefile46-91