Fullstack Starter

English | 한국어

Template versioning via Release Please — see CHANGELOG.md for release history.

Production-ready fullstack monorepo template with Next.js 16, FastAPI, Flutter, and GCP infrastructure.

3-Tier Architecture

graph TB
    subgraph Client
        Web[Next.js 16<br/>React 19]
        Mobile[Flutter 3.38<br/>Riverpod]
    end

    subgraph GCP["GCP Cloud Run"]
        API[FastAPI<br/>Python 3.12]
        Worker[Worker<br/>CloudTasks]
    end

    subgraph Data
        DB[(PostgreSQL 16)]
        Cache[(Redis 7)]
        Storage[(Cloud Storage)]
    end

    Web --> API
    Mobile --> API
    API --> DB
    API --> Cache
    API --> Worker
    Worker --> DB
    API --> Storage

    style Web fill:#0070f3,color:#fff
    style Mobile fill:#02569B,color:#fff
    style API fill:#009688,color:#fff
    style Worker fill:#009688,color:#fff
    style DB fill:#336791,color:#fff
    style Cache fill:#DC382D,color:#fff
    style Storage fill:#4285F4,color:#fff

Key Features

• Modern Stack: Next.js 16 + React 19, FastAPI, Flutter 3.38, TailwindCSS v4
• Type Safety: Full type support with TypeScript, Pydantic, and Dart
• Authentication: OAuth with better-auth (Google, GitHub, Facebook)
• Internationalization: next-intl (web), Flutter ARB (mobile), shared i18n package
• Auto-generated API Clients: Orval (web), swagger_parser (mobile)
• Infrastructure as Code: Terraform + GCP (Cloud Run, Cloud SQL, Cloud Storage)
• CI/CD: GitHub Actions + Workload Identity Federation (keyless deployment)
• AI Agent Support: Guidelines for AI coding agents (Gemini, Claude, etc.)
• mise Monorepo: mise-based task management and unified tool versions

Tech Stack

Why this tech stack? — Detailed reasoning behind each technology choice.

Quick Start

Choose one of the following methods to start with this template:

# Create from CLI
bun create fullstack-starter my-app
# or
npm create fullstack-starter my-app

Or use GitHub:

1. Click Use this template to create a new repository
2. Or Fork this repository

Prerequisites

Required for all platforms:

• mise - Runtime version manager
• Docker or Podman Desktop - Local infrastructure

For mobile development (iOS/Android):

• Xcode - Includes iOS Simulator (macOS only)
• Android Studio - Includes Android SDK and emulator

Optional:

• Terraform - Cloud infrastructure

1. Install Runtimes

# Install mise (if not installed)
curl https://mise.run | sh

# Install all runtimes (Node 24, Python 3.12, Flutter 3, bun, uv, Terraform)
mise install

2. Install Dependencies

# Install all dependencies at once
mise run install

3. Start Local Infrastructure

mise infra:up

This starts:

• PostgreSQL (5432)
• Redis (6379)
• MinIO (9000, 9001)

4. Run Database Migrations

mise db:migrate

5. Start Development Servers

# Start API and Web services (recommended for web development)
mise dev:web

# Start API and Mobile services (recommended for mobile development)
mise dev:mobile

# Or start all services
mise dev

Project Structure

fullstack-starter/
├── apps/
│   ├── api/           # FastAPI backend
│   ├── web/           # Next.js frontend
│   ├── worker/        # Background

...