Skip to content

development.md

Latest commit

 

History

History
119 lines (86 loc) · 3.9 KB

development.md

File metadata and controls

119 lines (86 loc) · 3.9 KB
Raw

Development Guide

How to get the demo running locally and what each part is doing once it's running.

Prerequisites

  • Node.js 20 or newer
  • pnpm 9 or newer
  • Docker Desktop (for PostgreSQL)
  • Xcode (for iOS) or Android Studio (for Android), if you want to run the mobile app on a simulator/emulator
  • A LAN-accessible API URL if you want to run on a physical device

First-time setup

From the repo root:

pnpm install

# Boot Postgres in the background
docker compose up -d postgres

# Configure the API
cp apps/api/.env.example apps/api/.env

# Run migrations and seed demo data
pnpm --filter @sdui/api exec prisma migrate dev
pnpm --filter @sdui/api db:seed

# Configure the admin and mobile envs
cp apps/admin/.env.example apps/admin/.env.local
cp apps/mobile/.env.example apps/mobile/.env.local

Edit apps/mobile/.env.local if you need a non-localhost API URL — see the comments in the file for iOS simulator, Android emulator, and physical device variants.

Running the three apps

Open three terminals:

pnpm dev:api      # NestJS  → http://localhost:3000/api
pnpm dev:admin    # Next.js → http://localhost:3001
pnpm dev:mobile   # Expo dev server, then press `i` for iOS or `a` for Android

The default URLs:

Service URL
API http://localhost:3000/api
Admin http://localhost:3001
Metro http://localhost:8081
PostgreSQL localhost:5432

Common workflows

Edit a screen and see it on the phone

  1. Open the admin (http://localhost:3001).
  2. Pick a screen (e.g. home).
  3. Drag, edit, save draft, then publish.
  4. Pull-to-refresh on the phone (or background and foreground the app).
  5. Mobile fetches the new published revision.

Reset the database

pnpm --filter @sdui/api exec prisma migrate reset
pnpm --filter @sdui/api db:seed

Type-check the whole monorepo

pnpm typecheck

Build everything

pnpm build

Hit the API from the command line

curl -sS \
  -H 'x-ui-schema-version: 1' \
  -H 'x-user-id: u_42' \
  -H 'x-client-os: ios' \
  -H 'x-client-os-version: 18.0' \
  -H 'x-client-app-version: 1.0.0' \
  http://localhost:3000/api/v1/screens/home | jq .

Debugging tips

  • Mobile can't reach the API. Check EXPO_PUBLIC_API_URL in apps/mobile/.env.local. iOS sim → localhost; Android emu → 10.0.2.2; device → your machine's LAN IP.
  • Admin save fails with 401. Confirm NEXT_PUBLIC_ADMIN_SECRET (admin) matches the x-admin-secret the API expects (default dev-only-secret).
  • Mobile shows stale layout. The cache is intentionally stale-while-revalidate. Pull to refresh, focus a different screen and back, or restart the app.
  • Schema validation error from the API. The ValidationPipe is set to forbidNonWhitelisted. If you sent extra fields, strip them. If a DTO is rejecting valid input, check that all decorators are correct in @sdui/contracts.
  • prisma migrate dev fails. Confirm Postgres is up (docker ps | grep sdui-postgres). If schema drift, run prisma migrate reset (destructive — wipes data).

Folder pointers

See also