A rails‑style DX for Go + React. Define your data once (Protobuf) and automatically get a Go API, DB models & migrations, a typed TS client with React Query hooks, and scaffolded CRUD UI components.

Stop wiring the same types, validators, handlers, queries, and hooks in three places. With fw, one schema produces everything you need—from database to browser—while keeping end‑to‑end types safe and codegen idempotent.

• One source of truth: /schema/**/*.proto.
• Generated automatically: ConnectRPC services, Ent models/migrations, TS SDK + React Query hooks, CRUD scaffolds.
• Customize safely: write business logic in service handlers; style UI with your own components.
• Drift control: fw gen ensures generated code stays in sync with schemas.

• Schema drift and copy‑paste glue across DB ↔ server ↔ client.
• Manual wiring of types, validation, and API handlers across multiple files.
• Slow time‑to‑first‑CRUD for Go teams that want a modern React front end.

fw composes Buf + ConnectRPC + Ent + Atlas + Vite + TanStack Query into one cohesive experience.

• Go server (ConnectRPC over HTTP/JSON) with request validation.
• DB layer: Ent models + Atlas schema migrations.
• Typed TS client + React Query hooks (useListUsers, useCreateUser, …).
• CRUD UI scaffolds for List / Detail / Create / Edit pages.
• Dev workflow: hot reload (Air, Vite), Docker Compose, structured logging.

# 1. Install core tools (one-time setup)
brew install go node pnpm bufbuild/buf/buf protobuf docker

# 2. Build the CLI
go build -o bin/fw .

# 3. Create a new project
./bin/fw init blog

# 4. Generate code (auto-installs dev tools on first run)
cd blog && ../bin/fw gen
# 📦 Installing atlas... ✅ Done
# 📦 Installing air... ✅ Done  
# 📦 Installing protoc-gen-*... ✅ Done
# ✅ Code generation complete!

# 5. Verify everything is ready
../bin/fw doctor
# ✅ All tools available!

# Clone and build
git clone https://github.com/apmitchell/fw
cd fw
go build -o bin/fw .

# Optional: Add to PATH for global access
sudo cp bin/fw /usr/local/bin/

# Or run directly
./bin/fw --help

Before using fw, ensure you have the following installed:

# Core development tools
brew install go node pnpm

# Protobuf and code generation
brew install buf protobuf

# Database and dev tools (optional but recommended)
brew install atlas-go cosmtrek/tap/air docker

# Verify installation
./bin/fw doctor

# Custom module path and npm scope
fw init myapp --module github.com/me/myapp --scope @me

fw uses a hybrid toolchain approach for the best developer experience:

brew install go node pnpm bufbuild/buf/buf protobuf docker

fw automatically installs these to ~/.fw/tools/ when needed:

• Atlas: Database schema migrations (via Homebrew tap, fallback to go install)
• Air: Hot reloading for Go development
• protoc-gen-go: Protocol buffer Go code generator
• protoc-gen-connect-go: ConnectRPC Go code generator

fw doctor  # Checks core tools + shows auto-install status

fw automatically keeps your project in sync with framework improvements:

Whenever you run fw gen, the framework:

1. Updates framework-managed files: package.json, tsconfig.json, Makefile, etc.
2. Preserves your code: Business logic, components, and user-written files remain untouched
3. Resolves dependencies: Automatically adds required packages (like @bufbuild/protobuf)
4. Fixes conflicts: Resolves common issues like duplicate exports

✅ Always synced (framework-managed):

• packages/sdk-ts/package.json — SDK dependencies and configuration
• packages/sdk-ts/src/index.ts — Generated exports and re-exports
• Build configuration files (tsconfig.json, Makefile, etc.)
• Docker and development configs

❌ Never touched (user-owned):

• Service handlers in server/internal/service/
• React components in web/src/
• Database schemas in server/internal/ent/schema/
• Custom business logic

• Stay current with framework improvements automatically
• No manual config updates when dependencies change
• Safe upgrades without breaking existing functionality
• Consistent tooling across all generated projects

fw init [name] creates this complete project structure:

myapp/
├── 📁 schema/                    # 🎯 Protobuf schemas (single source of truth)
│   ├── buf.yaml                  # Buf configuration
│   ├── buf.gen.yaml             # Code generation config
│   ├── common/v1/paging.proto   # Shared types (pagination, filters)
│   ├── error/v1/problem.proto   # Error handling schemas
│   └── user/v1/user.proto       # User service definition
├── 📁 server/                    # 🔧 Go API server
│   ├── go.mod                    # Go dependencies
│   ├── cmd/
│   │   ├── api/main.go          # HTTP server entrypoint
│   │   └── seed/main.go         # Database seeder
│   └── internal/
│       ├── app/config.go        # Configuration helpers
│       ├── ent/schema/          # Database schemas (Ent ORM)
│       │   ├── user.go          # User entity schema
│       │   └── mixin/           # Reusable schema components
│       ├── service/             # Business logic handlers
│       │   └── user_service.go  # User service implementation
│       └── transport/           # HTTP transport layer
│           ├── errors.go        # Error handling
│           └── validate.go      # Request validation
├── 📁 web/                       # ⚛️ React frontend
│   ├── package.json             # Frontend dependencies
│   ├── vite.config.ts          # Vite configuration
│   ├── tsconfig.json           # TypeScript configuration
│   ├── index.html              # HTML entry point
│   └── src/
│       ├── main.tsx            # React app entry
│       ├── App.tsx             # Main app component
│       ├── features/users/     # User management components
│       │   └── List.tsx        # User list component
│       └── lib/api/
│           └── client.ts       # ConnectRPC client setup
├── 📁 packages/sdk-ts/           # 📦 TypeScript SDK package
│   ├── package.json             # SDK package configuration
│   ├── tsconfig.json           # SDK TypeScript config
│   └── src/
│       ├── index.ts            # SDK exports
│       └── error.ts            # Error handling utilities
├── 📁 db/                        # 🗺️ Database configuration
│   └── atlas.hcl               # Atlas migration config
├── 📄 Root configuration files
│   ├── package.json            # Workspace configuration
│   ├── pnpm-workspace.yaml    # pnpm workspace setup
│   ├── Makefile                # Development commands
│   ├── docker-compose.yml     # PostgreSQL for development
│   ├── .env.example           # Environment variables template
│   ├── .air.toml              # Hot reload configuration
│   ├── .nvmrc                  # Node.js version specification
│   ├── .gitignore             # Git ignore patterns
│   └── README.md               # Project-specific documentation

Key Features of Generated Structure:

• Monorepo setup with pnpm workspaces
• ConnectRPC integration between Go server and React client
• Ent ORM with schema definitions and mixins
• Complete development workflow with hot reload and code generation
• Production-ready configuration for Docker, CI/CD, and deployment

• CLI framework with all commands (init, setup, gen, dev, migrate-up, doctor)
• Complete project scaffolding — generates 30+ files across full-stack structure
• Template synchronization — fw gen automatically updates framework-managed files (package.json, configs) while preserving user code
• Hybrid toolchain management:
  • Core tools via Homebrew (Go, Node, pnpm, Buf, protoc, Docker)
  • Auto-install dev tools (Atlas, Air, protoc-gen-*) to ~/.fw/tools/
  • Homebrew-first fallbacks with proper error reporting
• Protobuf schema templates with complete ConnectRPC service definitions
• Go backend with:
  • ConnectRPC service handlers (full CRUD operations)
  • Ent ORM schemas with mixins (timestamps, soft-delete, versioning)
  • Request validation and structured error handling
  • Database configuration (Atlas)
• React frontend with:
  • TypeScript + Vite configuration
  • TanStack React Query integration
  • CRUD UI components (UsersList with loading/error states)
  • ConnectRPC client setup
• TypeScript SDK with full protobuf codegen and React Query integration
• Development tooling (Air hot reload, pnpm workspaces, Docker Compose)
• Token replacement system (app name, module path, npm scope)

• ConnectRPC client-server communication testing
• Database migration + seeding validation
• Full fw dev workflow verification
• Error handling and developer experience polish

• One-command setup: fw init blog && fw gen creates and configures everything
• Auto-installing toolchain: Dev tools install automatically on first use
• Auto-syncing templates: Framework updates automatically apply to existing projects
• Working ConnectRPC services with CRUD operations (Create, Get, List, Update, Delete)
• Generated TypeScript SDK with full protobuf codegen and type safety
• React Query hooks ready for API integration (useQuery, useMutation)
• Ent ORM models with soft-delete, timestamps, and validation
• Rails-like DX: Download one binary, everything just works

CLI: Go, Cobra

Generated Project:

• Backend: Go 1.22, ConnectRPC, Ent ORM, PostgreSQL, Atlas migrations
• Frontend: React 18, TypeScript, Vite, TanStack Query
• Code Gen: Protobuf + Buf CLI, protovalidate
• Dev Tools: Air (hot reload), pnpm workspaces, Docker Compose

Contributions are welcome! Here's how to get started:

# Clone the repository
git clone https://github.com/apmitchell/fw
cd fw

# Build the CLI
go build -o bin/fw .

# Run the CLI
./bin/fw --help