https://github.com/sonofmagic/monorepo-template

icebreaker's monorepo template
https://github.com/sonofmagic/monorepo-template

action changesets docker husky monorepo pnpm turbo turborepo vscode

Last synced: 2 days ago
JSON representation

icebreaker's monorepo template

• Host: GitHub
• URL: https://github.com/sonofmagic/monorepo-template
• Owner: sonofmagic
• License: mit
• Created: 2022-11-02T16:18:16.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2026-02-22T00:27:34.000Z (24 days ago)
• Last Synced: 2026-02-22T02:26:30.670Z (23 days ago)
• Topics: action, changesets, docker, husky, monorepo, pnpm, turbo, turborepo, vscode
• Language: TypeScript
• Homepage: https://monorepo.icebreaker.top
• Size: 5.43 MB
• Stars: 44
• Watchers: 1
• Forks: 7
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# monorepo-template

[![codecov](https://codecov.io/gh/sonofmagic/monorepo-template/branch/main/graph/badge.svg?token=mWA3D53rSl)](https://codecov.io/gh/sonofmagic/monorepo-template)

English | [中文版本](README.zh-CN.md)

> 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

```text

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.