Mobile Boilerplate

🌐 Language: English · Tiếng Việt · 中文 · 한국어

Production-ready monorepo boilerplate for mobile apps: Flutter frontend + NestJS backend with end-to-end type safety via OpenAPI codegen.

Highlights

• 📱 Flutter feature-first + Riverpod + Dio + go_router
• 🚀 NestJS modular monolith + Prisma + Supabase Postgres + Pino
• 🔗 OpenAPI → Dart client codegen (one source of truth for the API contract)
• 🧪 Sample tests both sides (jest + e2e + flutter_test)
• 🛡️ Helmet + throttler + default-deny auth guard + PII redact in logs
• ✅ Lefthook + commitlint pre-commit/pre-push hooks; SHA-pinned GitHub Actions
• 🌍 i18n skeleton (en + vi) with flutter_localizations + intl
• 🔄 semantic-release (production + beta) gated by CI success

Tech Stack

Layer	Technology
Mobile	Flutter 3.27 + Riverpod 2 + Dio + go_router
Backend	NestJS 10 + Prisma 5 + Supabase Postgres + Pino
Monorepo	pnpm workspace + Melos
Toolchain	FVM + Volta + Node 20
Codegen	OpenAPI Generator (dart-dio)
CI/CD	GitHub Actions + semantic-release

Prerequisites

Minimum (backend-only dev):

• Node.js 20+ (managed by .nvmrc / Volta)
• pnpm 9+ (corepack enable && corepack prepare pnpm@9 --activate)

Required for full bootstrap (pnpm bootstrap:full) and mobile work:

• Flutter 3.27 via FVM — dart pub global activate fvm && fvm install
• Java 17 — required by openapi-generator-cli during pnpm codegen:api
• Melos — auto-activated by pnpm install:melos (uses fvm dart pub global activate melos)
• ~/.pub-cache/bin on PATH — so the melos binary is reachable after activation

Optional:

• Docker (for docker compose up api)
• Supabase project (or set SKIP_DB=true to skip the database for the hello flow)

Quick Start

# 1. Clone
git clone <repo-url> mobile-boilerplate
cd mobile-boilerplate

# 2. Configure backend env (use SKIP_DB=true to skip database for hello flow)
cp apps/api/.env.example apps/api/.env
# Optional: fill DATABASE_URL / DIRECT_URL from your Supabase project,
# or set SKIP_DB=true in .env to boot without a database.

# 3. Configure mobile env (default API_BASE_URL=auto resolves per platform)
cp apps/mobile/.env.example apps/mobile/.env

# 4. Install everything
#    Backend-only:  pnpm bootstrap         (just pnpm deps — no Flutter/Java needed)
#    Full stack:    pnpm bootstrap:full    (pnpm + activate melos + codegen + melos bootstrap)
pnpm bootstrap:full

# 5. Boot the backend
pnpm --filter @mobile-boilerplate/api dev
# → http://localhost:3000/api/hello
# → http://localhost:3000/api-docs    (Swagger UI; dev only)

# 6. Boot the mobile app (separate terminal)
cd apps/mobile
fvm flutter run --dart-define=FLAVOR=dev

First-time Flutter scaffold: the apps/mobile/ folder ships without native Android/iOS projects (those are generated by flutter create). Run cd apps && fvm flutter create --no-overwrite mobile --org com.example once after cloning to materialize them, then fvm flutter pub get.

Project Structure

mobile-boilerplate/
├── apps/
│   ├── api/              # NestJS backend
│   └── mobile/           # Flutter app
├── packages/
│   └── api_client/       # Generated Dart client (OpenAPI dart-dio)
├── tools/
│   ├── codegen/          # OpenAPI export + generation pipeline
│   └── scripts/          # Helper shell scripts
├── docs/                 # Multi-language documentation (en + vi/zh/ko mirrors)
└── .github/workflows/    # api-ci, mobile-ci, codegen-check, release

→ Full file map: docs/codebase-map.md

Common Commands

Command	Purpose
pnpm bootstrap	Install npm deps only (backend-only dev)
pnpm bootstrap:full	Full stack: pnpm + melos + codegen + pub get
pnpm --filter @mobile-boilerplate/api dev	Start backend with hot reload
cd apps/mobile && fvm flutter run --dart-define=FLAVOR=dev	Start mobile app
pnpm codegen:api	Regenerate Dart api_client
pnpm lint	Lint all (backend + mobile)
pnpm test	Test all
docker compose up api	Run backend in container

Documentation

Doc	Purpose
Getting started	First-time setup
Backend module recipe	Add NestJS module
Prisma module recipe	Add database model
Flutter feature recipe	Add mobile feature
API contract	Codegen flow
Overview	Scope, audience
Architecture	High-level design
Codebase map	File-tree quick ref
Code standards	Conventions
Design guidelines	UI/UX rules
Feature boundaries	Module isolation rules
Dependency injection	DI patterns
i18n guide	Translation workflow
Deployment	Release flow
Changelog	Release notes

→ Full index: docs/README.md

Contributing

Conventional commits required. Lefthook + commitlint enforce on commit/push. See docs/code-standards.md.

License

MIT