Monorepo Startup Kit 🚀

A production-grade monorepo starter template for building scalable modular SaaS applications with Next.js, TypeScript, and shadcn/ui.

Think: "Create Next App — but for modular enterprise systems."

📋 What's Inside?

This monorepo uses Turborepo and pnpm workspaces to manage multiple packages and applications.

Apps

• web: A Next.js 15 application with App Router, TypeScript, and Tailwind CSS

Packages

• @workspace/ui: Shared UI component library powered by shadcn/ui and Radix UI
• @workspace/cli: Command-line tool for project management (inspired by next-forge)
• @workspace/eslint-config: Shared ESLint configurations for the monorepo
• @workspace/typescript-config: Shared TypeScript configurations

🛠️ Tech Stack

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• Build System: Turborepo
• Package Manager: pnpm
• Version Management: Changesets
• Code Quality: ESLint, Prettier, TypeScript

🚀 Getting Started

Prerequisites

• Node.js >= 20
• pnpm >= 8

Installation

1. Clone the repository:

git clone <your-repo-url>
cd monorepo

2. Install dependencies:

pnpm install

3. Set up environment variables:

# Copy .env.example to .env.local in apps/web
cp apps/web/.env.example apps/web/.env.local

4. Start the development server:

pnpm dev

The web app will be available at http://localhost:3000

📦 Available Scripts

Development

# Start all apps in development mode
pnpm dev

# Start a specific app
pnpm dev --filter web

# Build all apps and packages
pnpm build

# Lint all packages
pnpm lint

# Type check all packages
pnpm check-types

# Format code with Prettier
pnpm format

# Check formatting
pnpm format:check

# Clean all build outputs and node_modules
pnpm clean

CLI Tool (Inspired by next-forge)

# Initialize a new project
pnpm cli init

# Update between versions with automatic migrations
pnpm cli update --from 0.1.0 --to 0.4.0

# Add components, pages, or API routes
pnpm cli add --component Card --type ui
pnpm cli add --component dashboard --type page

# Build CLI
pnpm cli:build

# Develop CLI in watch mode
pnpm cli:dev

📚 Full CLI Documentation →

Version Management

# Create a new changeset
pnpm changeset

# Version packages based on changesets
pnpm version-packages

# Build and release packages
pnpm release

🎨 Adding UI Components

To add shadcn/ui components to your project:

pnpm dlx shadcn@latest add button -c apps/web

This will add the component to packages/ui/src/components/, making it available across the entire monorepo.

Using Components

Import components from the UI package:

import { Button } from "@workspace/ui/components/button"

export default function Page() {
  return <Button>Click me</Button>
}

📝 Version Management with Changesets

This project uses Changesets for version management and changelog generation.

Creating a Changeset

When you make changes, create a changeset:

pnpm changeset

Follow the prompts to:

1. Select which packages changed
2. Choose the version bump type (major/minor/patch)
3. Write a description of your changes

Versioning

When ready to release:

# Update package versions and CHANGELOG.md
pnpm version-packages

# Build and publish (or create release PR)
pnpm release

Version Bump Guidelines

• Major: Breaking changes (e.g., API changes)
• Minor: New features (backward compatible)
• Patch: Bug fixes and minor improvements

🏗️ Project Structure

monorepo/
├── .changeset/              # Changeset configuration and files
├── .github/
│   └── workflows/           # GitHub Actions CI/CD
├── apps/
│   └── web/                 # Next.js application
│       ├── app/             # App Router pages and layouts
│       ├── components/      # App-specific components
│       └── lib/             # App-specific utilities
├── packages/
│   ├── ui/                  # Shared UI components
│   │   └── src/
│   │       ├── components/  # shadcn/ui components
│   │       └── lib/         # UI utilities
│   ├── eslint-config/       # Shared ESLint configs
│   └── typescript-config/   # Shared TypeScript configs
├── .cursorrules             # AI assistant configuration
├── CHANGELOG.md             # Project changelog
├── package.json             # Root package.json
├── pnpm-workspace.yaml      # pnpm workspace configuration
├── turbo.json               # Turborepo configuration
└── README.md                # This file

🔧 Configuration Files

.cursorrules

Contains comprehensive guidelines for AI-assisted development, including:

• Coding standards and best practices
• TypeScript and React patterns
• Performance optimization guidelines
• Security best practices

turbo.json

Configures the Turborepo build system:

• Task dependencies
• Caching strategies
• Pipeline configurations

pnpm-workspace.yaml

Defines the monorepo workspace structure for pnpm.

🔄 CI/CD

This project includes GitHub Actions workflows:

CI Workflow (.github/workflows/ci.yml)

Runs on every push and pull request:

• Linting
• Type checking
• Format checking
• Building

Release Workflow (.github/workflows/release.yml)

Runs on push to main:

• Automatically creates release PRs
• Versions packages using changesets
• Updates CHANGELOG.md

🎯 Best Practices

Code Organization

• Keep shared code in packages/
• Use workspace protocol for internal dependencies (workspace:*)
• Run commands from root using Turbo for caching benefits
• Maintain consistent tooling across packages

Development Workflow

1. Create a feature branch
2. Make your changes
3. Create a changeset: pnpm changeset
4. Commit your changes with conventional commit messages
5. Push and create a pull request

Commit Messages

Follow conventional commits:

feat: add new feature
fix: resolve bug
docs: update documentation
chore: update dependencies
refactor: improve code structure

🚢 Deployment

Vercel (Recommended)

1. Connect your repository to Vercel
2. Configure the root directory for the web app: apps/web
3. Vercel will automatically detect the Next.js configuration

Other Platforms

Ensure you:

• Set the build command: pnpm build --filter web
• Set the output directory: apps/web/.next
• Use Node.js >= 20

📚 Documentation

Project Documentation

• Documentation Index - Complete documentation navigation
• Quick Setup Guide - Get started in 5 minutes
• CLI Tool Guide - Complete CLI documentation
• Contributing Guide - How to contribute

External Resources

• Next.js Documentation
• Turborepo Handbook
• shadcn/ui Documentation
• pnpm Workspaces
• Changesets Documentation

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please read the contributing guidelines before submitting a PR.

1. Fork the repository
2. Create your feature branch
3. Add your changes and create a changeset
4. Push to the branch
5. Open a pull request

---

Built with ❤️ using modern web technologies