Developer Setup Guide

Get the Baby Basics API running locally for development.

Prerequisites

• Node.js 22 LTS
• Docker (for PostgreSQL)
• Git

1. Clone and Install

git clone https://github.com/FindingJohnny/baby-basics.git
cd baby-basics/apps/api
npm install

2. Start PostgreSQL

A local Docker Compose file runs PostgreSQL 16 with the default credentials (baby/baby):

docker compose -f ../../infra/docker-compose.local.yml up -d

3. Configure Environment

cp .env.example .env

The defaults work out of the box with the local Docker Compose setup:

Variable	Default	Purpose
DATABASE_URL	postgresql://baby:baby@localhost:5432/baby_basics	PostgreSQL connection
JWT_SECRET	change-me-to-a-random-string	Token signing (change for real use)
NODE_ENV	development	Environment mode
PORT	3000	API port
BASE_URL	http://localhost:3000	Public URL (used for share links)

Environment variables are validated at startup by src/env.ts using Zod (not @fastify/env). If a required variable is missing, the process exits with a clear error message.

4. Generate Prisma Client and Run Migrations

npx prisma generate
npx prisma migrate dev

5. Start the API

npm run dev

The API runs at http://localhost:3000. Verify with:

curl http://localhost:3000/api/v1/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-02-13T12:00:00.000Z",
  "version": "0.1.0",
  "db": "connected"
}

Available Scripts

Script	Command	Purpose
npm run dev	tsx watch + pino-pretty	Start dev server with hot reload and formatted logs
npm test	vitest run	Run tests
npm run test:watch	vitest	Run tests in watch mode
npm run lint	eslint	Lint source and test files
npm run lint:fix	eslint --fix	Auto-fix lint issues
npm run format	prettier --write	Format code
npm run typecheck	tsc --noEmit	Type check without emitting
npm run db:studio	prisma studio	Open Prisma Studio GUI

Running Tests

Tests require a separate PostgreSQL instance on port 5433 (to avoid conflicts with the dev database).

The docker-compose.local.yml file already starts both databases:

• Dev database: localhost:5432
• Test database: localhost:5433

To run tests:

# Start both dev and test databases (if not already running)
docker compose -f ../../infra/docker-compose.local.yml up -d

# Run tests
npm test

The test suite uses vitest with real Postgres (not SQLite). The setup-env.ts file automatically sets test environment variables, including the test database URL.

Project Structure

baby-basics/
├── apps/
│   ├── api/          # Fastify 5 + Prisma 7 REST API
│   ├── ios/          # SwiftUI iOS app (iOS 17+)
│   └── docs/         # Docusaurus documentation site
├── infra/            # Docker Compose, deploy/backup/rollback scripts
└── docs/specs/       # Feature specifications (source of truth)

iOS Setup

The iOS app requires Xcode 16+ and xcodegen.

Prerequisites

# Install xcodegen
brew install xcodegen

Generate Xcode Project

The .xcodeproj file is gitignored. Generate it from the YAML configuration:

cd apps/ios
xcodegen generate

This creates BabyBasics.xcodeproj from project.yml.

Build the App

xcodebuild build \
  -scheme BabyBasics \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro'

Run Tests

xcodebuild test \
  -scheme BabyBasicsTests \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro'

If the simulator name is not available, check installed simulators:

xcrun simctl list devices

Next Steps

• Read the Architecture Overview to understand the system design
• Browse the Specs for feature requirements
• Check apps/api/CLAUDE.md for API coding conventions