sbrubbles-forge

Production-grade Turborepo template for Next.js apps.

sbrubbles-forge is a comprehensive Next.js monorepo boilerplate for building modern, production-ready web applications. It provides a solid, opinionated foundation with enterprise-grade features, tooling, and best practices built-in.

Author: Beno Dresch sbrubbles@sbrubbles.work

✨ Features

• 🚀 Next.js 16 with App Router, Server Components, Server Actions & Turbopack
• ⚡ Turborepo for high-performance monorepo management with remote caching
• 🎨 Design System with shadcn/ui components, React Aria, and Tailwind CSS v4
• 🔐 Authentication with custom auth package
• 💾 Database setup with PostgreSQL + Drizzle ORM
• 📧 Email templates with React Email and preview server
• 🌍 Internationalization ready with i18n support
• 📊 Analytics with self-hosted Umami integration
• 💳 Payments infrastructure with Stripe
• 🔒 Security best practices (rate limiting, CSRF protection)
• 🔍 SEO optimization utilities
• 📦 Storage management with rustfs (S3-compatible)
• 🔔 Notifications system with ntfy integration
• 🔌 Webhooks handling with Svix
• 🧪 Testing setup with Vitest (unit) and Playwright (E2E)
• 📈 Observability with Sentry integration
• 🤖 AI/ML integrations ready
• 🎯 Type-safe with strict TypeScript configuration
• 🧹 Code Quality with Ultracite (Biome-powered)
• 🐳 Docker compose for local development services
• 📚 Storybook for component development and documentation

🚀 Quick Start

Clone this repository:

git clone https://github.com/sbrubbles-work/sbrubbles-forge.git
cd sbrubbles-forge
pnpm install

📋 Prerequisites

• Node.js >= 24.14.0
• pnpm 11.1.1 (or compatible)
• Docker (required for local services: PostgreSQL, Umami, GlitchTip, etc.)

🏗️ Project Structure

sbrubbles-forge/
├── apps/
│   ├── api/          # API routes and backend services (port 3006)
│   ├── app/          # Main Next.js application (port 3005)
│   ├── email/        # Email preview and development (port 3009)
│   ├── storybook/    # Component documentation (port 6006)
│   └── studio/       # Drizzle Studio database management (port 3008)
├── packages/
│   ├── ai/           # AI/ML integrations
│   ├── analytics/    # Analytics tracking
│   ├── auth/         # Authentication system
│   ├── database/     # Database schemas and migrations
│   ├── design-system/# UI components library
│   ├── email/        # Email templates
│   ├── localization/ # i18n support
│   ├── next-config/  # Shared Next.js configuration
│   ├── notifications/# Notification system
│   ├── observability/# Monitoring and logging (Sentry)
│   ├── payments/     # Payment processing
│   ├── rate-limit/   # Rate limiting utilities
│   ├── security/     # Security middleware and utilities
│   ├── seo/          # SEO helpers
│   ├── storage/      # File storage management
│   ├── testing/      # Testing utilities
│   ├── typescript-config/ # Shared TypeScript configs
│   └── webhooks/     # Webhook handlers
├── e2e/              # End-to-end tests (Playwright)
├── docker/           # Docker configurations & database scripts
└── scripts/          # Utility scripts

🎯 Apps Overview

Main Application (apps/app)

The primary user-facing Next.js application with:

• Server Components and Server Actions
• Authentication integration
• Database access via Drizzle ORM
• Analytics, notifications, and SEO utilities
• Responsive design system components
• Running on port 3005

API (apps/api)

Backend API services including:

• RESTful API routes
• Webhook handlers (Stripe, etc.)
• AI/ML integrations
• Payment processing
• Storage management
• Running on port 3006

Email Preview (apps/email)

Development environment for email templates:

• React Email components
• Live preview server
• Template testing
• Running on port 3009

Storybook (apps/storybook)

Component documentation and development:

• Interactive component showcase
• Design system documentation
• Visual testing
• Running on port 6006

Database Studio (apps/studio)

Drizzle Studio for database management:

• Browse database tables
• Run queries
• Manage data
• Running on port 3008

📦 Available Scripts

Development

pnpm dev           # Start all apps in development mode
pnpm build         # Build all apps and packages
pnpm start         # Start production build
pnpm test          # Run unit tests
pnpm e2e           # Run end-to-end tests

Code Quality

pnpm check         # Check code with Ultracite (linting + formatting)
pnpm fix           # Auto-fix issues with Ultracite
pnpm lint          # Lint code
pnpm analyze       # Analyze bundle sizes
pnpm boundaries    # Check architecture boundaries

Database

pnpm db:migrate    # Run database migrations
pnpm db:generate   # Generate migrations from schema
pnpm db:pull       # Pull schema from database
pnpm db:push       # Push schema to database
pnpm db:backup     # Backup PostgreSQL database
pnpm db:seed       # Seed database with sample data
pnpm studio        # Open Drizzle Studio (port 3008)

Docker Services

pnpm services:start # Start all Docker services (PostgreSQL, Umami, GlitchTip, etc.)

Release

pnpm release:patch  # Release patch version
pnpm release:minor  # Release minor version
pnpm release:major  # Release major version
pnpm changeset      # Create a changeset
pnpm release        # Publish changeset

🧰 Tech Stack

Frontend

• Framework: Next.js 15 with App Router & Turbopack
• UI Library: React 19
• Styling: Tailwind CSS (v4 with @tailwindcss/postcss)
• Components: shadcn/ui + React Aria Components
• State Management: React hooks + Server Components
• Forms: React Hook Form with Zod validation
• Data Fetching: Next.js Server Components & Server Actions

Backend

• Runtime: Node.js 24.14.0+
• Database: PostgreSQL with Drizzle ORM
• Authentication: Custom auth package
• API: Next.js API Routes & Server Actions
• Payments: Stripe integration
• Storage: File storage utilities
• Webhooks: Svix for webhook handling

Development Tools

• Monorepo: Turborepo
• Package Manager: pnpm 11.1.1
• Language: TypeScript (strict mode)
• Linting/Formatting: Ultracite (Biome engine)
• Testing: Vitest (unit) + Playwright (E2E)
• Component Dev: Storybook
• Email Dev: React Email
• Bundle Analysis: Next.js analyzer

DevOps & Monitoring

• Error Tracking: Sentry
• Analytics: Umami (self-hosted)
• Containerization: Docker & Docker Compose
• CI/CD: Release-it + Changesets
• Local Services:
  • PostgreSQL (database)
  • Umami (analytics)
  • GlitchTip (error tracking alternative)
  • Valkey (Redis alternative, caching)
  • ntfy (notifications)
  • rustfs (file storage)

🔧 Configuration

TypeScript Configuration

All packages extend from @repo/typescript-config for consistent type checking across the monorepo.

Tailwind CSS

Shared Tailwind v4 configuration via @repo/design-system with PostCSS integration.

Next.js

Base configuration shared through @repo/next-config with optimizations for:

• Standalone output for production
• Sentry integration
• Bundle analysis
• Turbopack in development

Environment Variables

Create .env.local files in the root and/or individual apps. Key variables include:

# Database
DATABASE_URL=postgresql://postgres:mypassword@localhost:5432/postgres

# Authentication
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3005

# Payments (if using Stripe)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Storage
STORAGE_URL=http://localhost:9000

# Analytics
ANALYTICS_URL=http://localhost:6005

# Monitoring
SENTRY_DSN=https://...

Shared Packages

Each workspace package (e.g., @repo/auth, @repo/database) can be imported directly:

import { auth } from '@repo/auth';
import { db } from '@repo/database';
import { Button } from '@repo/design-system';

🧪 Testing

The project includes comprehensive testing infrastructure:

Unit Tests (Vitest)

• Run all unit tests: pnpm test
• Tests are located in __tests__ directories alongside source code
• Configuration via @repo/testing package
• Fast execution with Vitest's watch mode

E2E Tests (Playwright)

• Run E2E tests: pnpm e2e
• Tests located in e2e/tests/
• Multi-browser support (Chromium, Firefox, WebKit)
• Screenshots and traces saved in e2e/test-results/
• HTML reports generated in e2e/playwright-report/

Example E2E Test Coverage

Current E2E tests include:

• Sign-in flow validation
• Form validation and error handling
• User authentication scenarios

Running Tests

# Unit tests
pnpm test              # Run all unit tests

# E2E tests
pnpm e2e              # Run all E2E tests
pnpm e2e --ui         # Run with Playwright UI
pnpm e2e --headed     # Run in headed mode

🐳 Local Development with Docker

Start all local services at once:

pnpm services:start

This command starts the following Docker services defined in docker/docker-compose.yml:

• PostgreSQL (port 5432) - Primary database
• Umami (port 6005) - Self-hosted analytics platform
• GlitchTip (port 8005) - Open-source error tracking
• Valkey (port 6379) - Redis-compatible caching layer
• ntfy (port 8010) - Notification delivery service
• rustfs (ports 9000-9001) - S3-compatible file storage

Database Management

Backup and restore PostgreSQL databases:

pnpm db:backup     # Creates timestamped backup in docker/backups/
pnpm db:seed       # Seeds database with sample data

The docker/init-db.sql script automatically creates multiple databases on first startup.

🚦 Development Workflow

1. Start Docker services

   pnpm services:start

2. Run database migrations

   pnpm db:push

3. Start development servers

   pnpm dev

   This will start:

   • Main app on http://localhost:3005
   • API on http://localhost:3006
   • Storybook on http://localhost:6006
   • Email preview on http://localhost:3009
   • Database studio on http://localhost:3008

4. Code quality checks

   pnpm check    # Check for issues
   pnpm fix      # Auto-fix issues

5. Run tests

   pnpm test     # Unit tests
   pnpm e2e      # E2E tests

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

• Next.js
• Turborepo
• Drizzle ORM
• shadcn/ui
• Tailwind CSS
• Ultracite

📞 Support

For issues and questions:

• GitHub Issues: sbrubbles-work/sbrubbles-forge/issues
• Email: sbrubbles@sbrubbles.work

🤝 Contributing

Contributions, issues, and feature requests are welcome!

---

Built with ❤️ using Next.js, Turborepo, and modern web technologies.