monorepo-template

English | 中文版本

A modern pnpm + Turbo Repo + Changesets starter that helps you bootstrap production-ready monorepos quickly.

Overview

monorepo-template is a production-oriented pnpm + Turbo monorepo template. It ships with unified build, test, release, linting, and commit conventions, making it ideal for teams maintaining multiple deployable apps alongside reusable packages.

Key Features

• Modular Architecture: Template sources live under templates/ while reusable tooling lives in packages/, keeping responsibilities clear.
• Centralized Scaffolding Assets: @icebreakers/monorepo-templates packages templates and assets for both monorepo and create-icebreaker.
• Unified Toolchain: pnpm workspaces, Turbo task pipelines, Vitest, and Changesets streamline the entire lifecycle from development to release.
• Engineering Standards: ESLint, Stylelint, Husky, and Commitlint keep code quality high and commit messages consistent.
• Extensible Template: Helper scripts (script:init, script:sync, script:clean, etc.) from @icebreakers/monorepo keep dependencies and scaffolding aligned.
• CI/CD Ready: Sample GitHub Actions configuration, Codecov integration, and secrets.NPM_TOKEN support automated publishing and coverage reporting.

Quick Start

1. Prepare environment: Ensure Node.js >= 20 and run corepack enable so pnpm is available.
2. Install dependencies: Run pnpm install to fetch every workspace dependency.
3. Local development: Use pnpm dev to launch Turbo parallel dev scripts and iterate within each app.
4. Build and verify: Run pnpm build, pnpm test, and pnpm lint to validate builds, tests, and linting.
5. Template cleanup (optional): Use pnpm script:clean to prune sample packages when personalising the template.

Bootstrap shortcuts

• Zero-install cleanup on a fresh clone: pnpm dlx @icebreakers/monorepo@latest clean --yes (add --include-private to keep private packages in scope).
• One-liner scaffold: pnpm create icebreaker or npm create icebreaker@latest enters interactive mode, asks for the target directory, and lets you select which templates to keep. Use --templates tsup,vue-hono or --templates 2,5 to preselect.

Repository Layout

templates/
  cli/          # CLI application scaffold
  client/       # Web client (e.g., Vue/React)
  server/       # Server or API layer
  vitepress/    # Static site or documentation portal
  tsup/         # Library template powered by tsup
  tsdown/       # Library template powered by tsdown
  unbuild/      # Library template powered by unbuild
  vue-lib/      # Vue component library template
packages/
  monorepo/           # @icebreakers/monorepo helper scripts
  create-icebreaker/  # npm create flow
  monorepo-templates/ # template and asset bundle for npm

• templates/cli: Sample CLI app scaffold.
• templates/client: Sample rich web client application.
• templates/server: Entry point for server or API services.
• templates/vitepress: Static marketing or documentation site starter.
• templates/tsup: Library template powered by tsup.
• templates/tsdown: Library template powered by tsdown.
• templates/unbuild: Library template powered by unbuild.
• templates/vue-lib: Vue component library template.
• packages/*: Reusable packages and scaffolding shared across apps.
• Root configuration files (turbo.json, tsconfig.json, eslint.config.js, etc.) enforce consistent settings across the monorepo.

Common Scripts

Command	Description
pnpm install	Install workspace dependencies.
pnpm dev	Run every workspace exposing a dev script in parallel.
pnpm build	Execute a repository-wide build through Turbo.
pnpm test / pnpm test:dev	Run Vitest once or in watch mode.
pnpm lint	Apply ESLint and Stylelint checks across the monorepo.
pnpm changeset	Create an interactive Changeset for version bumps.
pnpm publish-packages	Build, lint, test, then version and publish changed packages.
pnpm script:init	Initialise template settings via @icebreakers/monorepo.
pnpm script:sync	Synchronise dependency and script versions.
pnpm script:clean	Remove sample packages and generated artifacts.

Template Workflow

• Use pnpm create icebreaker to scaffold a trimmed workspace in a new directory.
• Install dependencies and start development with pnpm install and pnpm dev.
• Add or remove apps/packages as your workspace evolves.

Release & Versioning

Leverage Changesets plus GitHub Actions for automated versioning:

1. Capture changes with pnpm changeset, marking each update as patch, minor, or major.
2. After merging, run pnpm publish-packages locally or let CI publish from the main branch.
3. Configure secrets.NPM_TOKEN in GitHub to allow npm publishing.

Quality Assurance

• Code style: .editorconfig enforces two-space indentation and LF line endings, while ESLint and Stylelint maintain consistency across packages.
• Commit hooks: Husky and lint-staged run eslint --fix, vitest, and other checks before commits.
• Testing & coverage: Run pnpm test -- --coverage to export coverage reports into the coverage/ directory.
• Staying current: Use npx @icebreakers/monorepo@latest to upgrade this template when new features ship.

More Resources

• Documentation: https://monorepo.icebreaker.top/
• Contributing guide: See CONTRIBUTING.md for workflow details.
• Code of Conduct: Review CODE_OF_CONDUCT.md to understand community expectations.
• Security policy: Follow SECURITY.md to report security issues.
• License: Refer to LICENSE for the full open-source license text.