React Router Gospel Stack with Turborepo

React Router TypeScript monorepo with Turborepo pipelines, Drizzle/Prisma ORM, Turso/PostgreSQL database, Docker deploy to Fly.io, pnpm, shadcn/ui, and TailwindCSS.

Important

This used to be the remix-gospel-stack (Remix v2) but to follow remix merging back into react router, the stack was converted to React Router v7+. And the name was changed to react-router-gospel-stack.

In this migration, we made other adjustments to the stack that reflects what I'm using in production SaaS apps:

• Using Turso instead of LiteFS (decision)
• Dropping the NextJS app and the Vercel deployments (I was not using them so difficult to maintain)
• We now use pnpm catalogs to define our versions in one file.

Quick Start

Recommended: Using degit

pnpm dlx degit PhilDL/react-router-gospel-stack my-app
cd my-app
pnpm install
pnpm run setup

Alternative: Clone the Repository

git clone [email protected]:PhilDL/react-router-gospel-stack.git my-app
cd my-app
pnpm install
pnpm run setup

💽 This repository is opiniated:

• TypeScript only
• Only compatible with pnpm package manager to handle monorepo workspaces
• Uses turborepo pipelines + cache to build, lint, typecheck, and test the monorepo

What's in the Stack

This is a monorepo for building modern web applications with React Router, optimized for developer experience and deployment simplicity.

Core Technologies

• 🚀 React Router v7+ - Modern full-stack React framework
• 📦 Turborepo - High-performance build system for monorepos
• 🗄️ Database - Choose between:
  • Turso - Distributed SQLite with libSQL
  • PostgreSQL - Multi-region Fly PostgreSQL Cluster
• 🛠️ ORM - Choose between:
  • Drizzle - SQL-like TypeScript ORM
  • Prisma - Type-safe database toolkit
• 🎨 shadcn/ui - UI Components system
• 🎯 TailwindCSS 4 - Utility-first CSS framework
• 🐳 Docker - Containerized deployment
• 🪂 Fly.io - Multi-region deployment platform

Developer Tools

• 🦾 TypeScript - Full ts setup
• 🧪 Vitest - Fast unit testing
• 🎭 Playwright - End-to-end testing
• 🔍 ESLint - Code linting
• 💅 Prettier - Code formatting
• 🔄 GitHub Actions - CI/CD pipelines

Monorepo Structure

• apps/ - Your applications (React Router webapp included)
• packages/ - Shared code, UI components, database, business logic
• config/ - ESLint, tsconfig, and other configuration packages

Documentation

• 🚀 Initialization Guide - Set up a new project from this template
• 📚 Architecture - Understand the monorepo structure and packages
• 🛠️ Development Guide - Set up your local development environment
• 🗄️ Database Guide - Configure PostgreSQL or Turso, migrations, and switching
• ☁️ Deployment Guide - Deploy to Fly.io with Docker
• 🎨 UI Package - Work with shadcn/ui components
• 🧪 Testing Guide - Run tests, linting, and typechecking

Key Decisions

If you knew this stack from a previous version, here are some decisions documents that explain why certain things changed:

• Why Drizzle Over Prisma?
• Why Turso instead of LiteFS?

Support & Contributing

• ⭐ Found this useful? Give it a star!
• 🐛 Found a bug? Open an issue
• 💡 Have an improvement? Submit a PR

See CONTRIBUTING.md for contribution guidelines.

Thanks & Credits

• The ESM setup is heavily inspired by the epic-stack by @kentcdodds
• Thanks to @shadcn for the amazing component library
• UI integration and practices borrowed from @juliusmarminge's acme-corp monorepo

Disclaimer

I am learning and improving this stack continuously. The setup proposed here is one of many possible approaches. If you see any possible improvements, please submit a PR — I will appreciate it greatly!

License

MIT