A production-ready monorepo showcasing modern web development with Next.js 15, React 19, and a thoughtfully-architected feature module system.

turborepo-nextjs.vercel.app

Clear separation between presentation, business logic, and data. Feature modules follow a strict no-barrel-files convention to prevent bundle bloat and maintain clear server/client boundaries in React Server Components.

End-to-end type safety with tRPC—from database queries to API responses to client components. If it compiles, it works.

Includes authentication (Clerk), background jobs (Inngest), database (PostgreSQL + Prisma on NeonDB), AI integration (OpenAI + E2B sandboxes), and comprehensive error handling.

• Next.js 15 — App Router, React Server Components, Turbopack
• React 19 — Latest concurrent features and optimizations
• TypeScript — Strict mode, zero compromises
• Turborepo — Monorepo with intelligent caching

• tRPC — End-to-end typesafe APIs with superjson transformer
• PostgreSQL + Prisma — Relational database with type-safe ORM, hosted on NeonDB (serverless Postgres)
• TanStack Query — Server state management, caching, & synchronization

• Clerk — Complete auth with GitHub OAuth, middleware-protected routes
• Inngest — Durable async workflows and background processing

• Tailwind CSS 4 — Modern CSS with native cascade layers
• Shadcn/UI + Radix UI — 60+ accessible components
• next-themes — Seamless dark mode
• Lucide Icons — Beautiful, consistent iconography

• Biome — Blazing fast linting & formatting (replaces ESLint + Prettier)
• Sherif — Validates monorepo dependencies
• Storybook — Component documentation & visual testing

• OpenAI — GPT integration for intelligent features
• E2B Code Interpreter — Sandboxed code execution
• Cloudinary — Media management & optimization

turborepo-nextjs/
├── apps/
│   ├── web/                    # Main Next.js application
│   │   ├── app/                # App Router (route groups & pages)
│   │   │   ├── (home)/         # Public routes: /, /pricing, /auth
│   │   │   ├── api/            # API routes: tRPC, webhooks, Inngest
│   │   │   └── projects/       # Protected routes: /projects/*
│   │   │
│   │   ├── modules/            # 🎯 Feature modules (domain-driven)
│   │   │   ├── home/           # Home page features
│   │   │   ├── projects/       # Project management
│   │   │   ├── messages/       # Message handling
│   │   │   ├── usage/          # Usage tracking
│   │   │   └── layout/         # Shared layout components
│   │   │
│   │   ├── trpc/               # tRPC setup & routers
│   │   ├── inngest/            # Background job definitions
│   │   ├── prisma/             # Database schema & migrations (PostgreSQL)
│   │   ├── middleware.ts       # Auth protection (Clerk)
│   │   └── env.mjs             # Type-safe environment variables
│   │
│   └── storybook/              # Component playground (60+ stories)
│       └── stories/            # Visual documentation for all UI components
│
└── packages/
    ├── design-system/          # Shared UI library
    │   └── src/
    │       ├── components/     # Shadcn UI components (ui/ & magicui/)
    │       ├── hooks/          # Reusable React hooks
    │       └── lib/            # Utilities (cn, etc.)
    │
    └── typescript-config/      # Shared TypeScript configurations
        ├── base.json           # Base strict config
        ├── nextjs.json         # Next.js specific
        └── react-library.json  # For packages

• Node.js 24.6.0+ (LTS recommended)
• pnpm 10.14.0+
• PostgreSQL database (NeonDB recommended, or local/Docker)

# 1. Clone the repository
git clone https://github.com/nass59/turborepo-nextjs.git
cd turborepo-nextjs

# 2. Install dependencies
pnpm install

# 3. Set up environment variables
cp apps/web/.env.example apps/web/.env.local
# Then edit apps/web/.env.local with your keys

# 4. Set up database & generate Prisma client
cd apps/web && pnpm prisma generate && pnpm prisma db push && cd ../..

# 5. Start all development servers
pnpm dev

That's it! Your apps will be running:

• 🌐 Web app: localhost:3000
• 📚 Storybook: localhost:6006

# Development
pnpm dev              # Start all apps (web + storybook)
pnpm build            # Build all packages & apps for production
pnpm typecheck        # Run TypeScript checks across workspace
pnpm lint             # Lint all code with Biome
pnpm format           # Auto-format code with Biome

# Dependencies
pnpm check-dependencies  # Validate with Sherif
pnpm bump-deps          # Update all dependencies (except geist)
pnpm bump-ui            # Sync Shadcn UI components to design-system

# Cleanup
pnpm clean             # Remove build artifacts & caches

# Web App (apps/web)
cd apps/web
pnpm dev              # Start with Turbopack (fast refresh)
pnpm build            # Production build
pnpm start            # Start production server
pnpm typecheck        # Type check this app

# Storybook (apps/storybook)
cd apps/storybook
pnpm dev              # Start Storybook dev server
pnpm build            # Build static Storybook site
pnpm chromatic        # Deploy to Chromatic (visual testing)

1. Add a new module in apps/web/modules/your-feature/

   modules/your-feature/
   ├── ui/              # Components
   ├── server/          # Server functions
   ├── types.ts         # Types
   └── constants.ts     # Config
   

2. Create tRPC procedures in apps/web/trpc/routers/your-feature.ts

   import { protectedProcedure } from '../trpc';
   
   export const yourFeatureRouter = {
     list: protectedProcedure.query(async ({ ctx }) => {
       // Server-side logic with ctx.clerkUserId
     }),
   };

3. Use in components via tRPC hooks

   'use client';
   import { useTRPC } from '@/trpc/client';
   
   export function YourComponent() {
     const { data } = useQuery(trpc.yourFeature.yourAction.queryOptions());
     // ...
   }

1. Add to design system via Shadcn CLI

   pnpm bump-ui  # Syncs latest Shadcn components

2. Create Storybook story in apps/storybook/stories/

   import type { Meta, StoryObj } from '@storybook/react';
   import { YourComponent } from '@workspace/design-system/components/ui/your-component';
   
   const meta: Meta<typeof YourComponent> = {
     title: 'UI/YourComponent',
     component: YourComponent,
   };

3. Use in your app

   import { YourComponent } from '@workspace/design-system/components/ui/your-component';

Define Inngest functions in apps/web/inngest/functions.ts:

import { inngest } from './client';

export const processTask = inngest.createFunction(
  { id: 'process-task' },
  { event: 'app/task.process' },
  async ({ event, step }) => {
    // Durable async workflow
  }
);

This project includes comprehensive documentation for AI assistants:

• docs/AI-DEVELOPMENT-GUIDE.md — Guidelines for AI pair programming
• .github/copilot-instructions.md — GitHub Copilot specific instructions
• ADRs — Architectural Decision Records in docs/adr/
• JSDoc — All public APIs documented

Helpful Scripts:

./scripts/ai-analysis.sh       # Generate project analysis
./scripts/adr-helper.sh new    # Create new ADR
./scripts/debug-helper.sh      # Debug assistance

• Architecture Decision Records — Why we made key technical choices
• AI Development Guide — Guidelines for AI-assisted development
• Copilot Instructions — Project conventions for GitHub Copilot

• 0002: Turborepo for Monorepo Management
• 0005: PostgreSQL with Prisma for User Data
• 0006: Clerk Authentication
• 0010: API Design Standards (tRPC)

The @workspace/design-system package exports 60+ accessible components built on:

• Radix UI primitives
• Tailwind CSS 4 styling
• CVA (class-variance-authority) for variants
• Lucide Icons for iconography

Usage:

// Direct imports (no barrel files)
import { Button } from '@workspace/design-system/components/ui/button';
import { cn } from '@workspace/design-system/lib/utils';

Explore components:

cd apps/storybook && pnpm dev
# Visit http://localhost:6006

# Connect your repo to Vercel
vercel

# Add environment variables in Vercel dashboard
# Deploy!
vercel --prod

# Build
docker build -t turborepo-nextjs .

# Run
docker run -p 3000:3000 turborepo-nextjs

Ensure all required env vars are set in your deployment platform. Turborepo will automatically pass them through during build (configured in turbo.json).

This project is licensed under the MIT License — see LICENSE.md for details.

Built with amazing open source tools:

• Vercel — Hosting & deployment platform
• Shadcn — UI component design
• Turborepo Team — Monorepo tooling
• Next.js Team — The React framework
• Biome — Fast, unified toolchain
• tRPC — End-to-end type safety
• Clerk — Beautiful authentication

• Add comprehensive test coverage
• Implement E2E testing with Playwright
• Add performance monitoring (Sentry)
• Add CI/CD workflows
• Internationalization (i18n)

Built with ❤️ by nass190