monorepo-starter v1.2.5

Turbo Stack CLI

Turbo Stack CLI is a command-line tool to bootstrap a preconfigured monorepo architecture optimized for modern development workflows. It provides a robust foundation for building scalable applications with a focus on developer experience and code maintainability.

Table of Contents

• Features
• Tech Stack
• Project Structure
• Environment Setup
• Getting Started
• Development Workflow
• Contributing
• License

Features

• TurboRepo Integration: A high-performance build system that leverages intelligent caching and parallel execution to significantly reduce build times. It automatically tracks dependencies between packages and apps to ensure efficient rebuilds.

• Apps

  • Next.js Web Application: A feature-rich React framework application preconfigured with:
    • Server-side rendering
    • API routes
    • File-based routing
    • Built-in optimization features
  • Storybook Workshop: An isolated UI development environment that allows you to:
    • Develop components in isolation
    • Test edge cases easily
    • Document component usage
    • Share components across teams

• Reusable Packages:

  • UI Package: A collection of reusable UI components optionally based on ShadCN UI, providing:
    • Consistent design language
    • Accessibility-first components
    • Customizable theming
    • Type-safe props
  • Database Package: Prisma ORM setup with TSUP for building, offering:
    • Type-safe database queries
    • Auto-generated migrations
    • Database schema management
    • Efficient TypeScript/JavaScript compilation
  • Config Package: Centralized configuration for:
    • Prettier - Consistent code formatting
    • ESLint - Code quality enforcement
    • TypeScript - Type safety and developer tooling

• Continuous Integration: Predefined GitHub Actions workflow that:

  • Validates code quality
  • Ensures type safety
  • Verifies build integrity
  • Maintains consistent coding standards

• Developer Tooling:

  • VSCode settings for consistent development experience
  • Integrated debugging configurations
  • Recommended extensions

Tech Stack

Core Technologies

• TurboRepo: An incremental bundler and build system optimized for JavaScript and TypeScript monorepos. It handles the complexity of managing multiple packages and applications within a single repository.

• Next.js: A powerful React framework that provides a robust foundation for building web applications with features like server-side rendering, static site generation, and API routes.

• TypeScript: A typed superset of JavaScript that enhances developer productivity through better tooling and error catching.

• Prisma: A modern database toolkit that provides a type-safe and intuitive way to interact with your database through generated queries.

• Storybook: A UI development environment for building, documenting, and testing components in isolation.

Environment Management

• @t3-oss/env-core: A library for managing type-safe environment variables across your entire monorepo.

• @t3-oss/env-nextjs: Next.js-specific environment variable validation and typing, ensuring type safety for environment variables in your Next.js applications.

Development Tools

• ESLint: A pluggable linting utility that helps maintain code quality and consistency.

• Prettier: An opinionated code formatter that ensures consistent code style across your project.

• cspell: A spell checker for code that helps catch spelling errors in identifiers, strings, and comments.

Project Structure

.
├── .github/                  # CI workflows
├── .turbo/                   # TurboRepo configuration
├── .vscode/                  # VSCode settings
├── apps/
│   ├── web/                 # Next.js application
│   └── workshop/            # Storybook application
├── packages/
│   ├── config/             # Shared configurations
│   ├── database/           # Prisma setup
│   └── ui/                 # UI components
├── docker-compose.yml       # Docker services configuration
├── cockroach-data/         # CockroachDB data directory
└── [Configuration Files]

Key Directories and Files

.github/workflows

Contains CI workflows that perform:

• Spell checking using cspell to maintain code quality
• Linting with ESLint to ensure code consistency
• Type checking with TypeScript to prevent type-related errors
• Build verification to ensure all packages and apps build successfully

apps/web

Next.js application featuring:

• Type-safe environment variables using @t3-oss/env-nextjs
• Integration with shared UI components
• Scalable architecture for enterprise applications
• Performance optimizations out of the box

apps/workshop

Storybook application providing:

• Isolated component development environment
• Interactive component testing
• Comprehensive documentation
• Visual regression testing capabilities

packages/

Shared packages containing:

• ui: Reusable component library with optional ShadCN UI integration
• database: Prisma ORM configuration and database utilities
• config: Centralized tooling configuration for consistent development experience

Environment Setup

Development Services

The project uses Docker to manage development services, including the database. The configuration is defined in docker-compose.yml:

services:
  cockroach:
    container_name: monorepo-starter-cockroach-dev
    image: cockroachdb/cockroach:latest
    restart: always
    ports:
      - '26258:26257'
      - '8082:8080'
    command: start-single-node --insecure
    volumes:
      - '${PWD}/cockroach-data/crdb:/cockroach/cockroach-data'

Managing services is simple with the provided scripts:

# Start the database and other services
yarn db:start

# Stop all services
yarn db:stop

Service access points:

• CockroachDB UI: http://localhost:8082
• Database port: 26258

You can extend the docker-compose.yml to include additional services needed for your development environment, such as Redis, Elasticsearch, or other databases.

Environment Variables

The project uses t3-env for type-safe environment variables. Create a .env file in the root directory with the following variables:

# Database connection URL
DATABASE_URL="postgresql://..."

# Add other variables as needed

The type safety is enforced through schema definitions:

// Schema definition example
import { createEnv } from '@t3-oss/env-core'

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  runtimeEnv: process.env,
})

For Next.js applications, you can use @t3-oss/env-nextjs which provides additional Next.js-specific validations:

// apps/web/env.ts
import { createEnv } from '@t3-oss/env-nextjs'

export const env = createEnv({
  // ... configuration
})

Getting Started

1. Create a new monorepo:

   npx monorepo-starter init

2. Navigate to project directory:

   cd my-monorepo

3. Install dependencies:

   yarn install

4. Set up environment variables:

   cp .env.example .env

5. Start development servers:

   yarn dev

Development Workflow

Prerequisites

• Node.js version >= 22
• Yarn version >= 1.22
• Docker installed on your machine
• Docker Compose (usually included with Docker Desktop)

Starting Development Environment

1. Start the database:

   yarn db:start

2. Start the development servers:

   # Start all apps
   yarn dev
   
   # Or start a specific app
   yarn dev --filter=web
   yarn dev --filter=workshop

3. Access services:

   • CockroachDB UI: http://localhost:8082
   • Database port: 26258

Building Packages

Build all packages and applications:

yarn build

This command:

• Compiles TypeScript code
• Bundles assets
• Generates necessary files
• Respects dependencies between packages

Type Checking

Run type checking across the entire monorepo:

yarn typecheck

Linting

Lint all files in the monorepo:

yarn lint

Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add my feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

Ensure all workflows pass locally before submitting.

License

MIT License