| name | js-monorepo |
| description | JS/TS monorepo with pnpm workspaces and Turborepo. Use when setting up a monorepo, adding packages, or auditing config.
|
JS Monorepo
Set up and maintain JavaScript/TypeScript monorepos with pnpm workspaces, Turborepo, and shared packages.
Critical Rules
- pnpm workspaces only - No yarn workspaces, no npm workspaces. pnpm is the package manager.
- Turborepo for task orchestration - All cross-package scripts go through turbo.
- Two non-negotiable packages - Every monorepo MUST have
contracts and ui packages.
workspace:* protocol - Apps reference internal packages via "@your-org/contracts": "workspace:*".
- pnpm catalogs for external deps - Define versions once in
pnpm-workspace.yaml, reference via catalog: protocol.
- Root owns tooling - ESLint, Prettier, TypeScript base config, Husky all live at the root.
- Packages own their tsconfig - Each package extends
tsconfig.base.json from root.
- Standardized script names - All packages use the same turbo-compatible script names (Read references/package-patterns.md for the full script table).
- Bootstrap script is mandatory - New developers must be able to run one command to get started.
Sub-Commands Overview
| Command | Purpose |
|---|
/js-monorepo init | Set up a new monorepo from scratch |
/js-monorepo add-package | Add a shared package to an existing monorepo |
/js-monorepo review | Audit existing monorepo for issues |
Monorepo Structure
your-project/
├── apps/ # Deployable applications
│ ├── web-app/ # Next.js frontend
│ └── api/ # NestJS/Express backend
├── packages/ # Shared packages
│ ├── contracts/ # NON-NEGOTIABLE: Types, Zod schemas, interfaces
│ └── ui/ # NON-NEGOTIABLE: React components, hooks, patterns
├── scripts/ # Monorepo scripts (bootstrap, pre-commit, etc.)
├── turbo.json # Turborepo pipeline
├── pnpm-workspace.yaml # Workspace definition + dependency catalogs
├── tsconfig.base.json # Shared TypeScript config
├── eslint.config.mjs # ESLint 9 flat config (root)
├── prettier.config.mjs # Prettier config (root)
├── .prettierignore # Prettier ignore patterns
├── .gitignore # Git ignore patterns
├── .editorconfig # Editor settings
├── .husky/pre-commit # Pre-commit hook
└── package.json # Root: engines, scripts, devDependencies
Before Any Sub-Command
- Read references/config-templates.md - Root config file templates
- Read references/scripts-templates.md - Script and runtime config templates
- Read references/package-patterns.md - Package structure, scripts, and guidance
- Read references/shadcn-setup.md - shadcn/ui initialization and monorepo wiring (if project uses shadcn)
Sub-Commands
/js-monorepo init
When: Setting up a new monorepo from scratch or converting an existing project.
Steps:
-
Scaffold directory structure:
mkdir -p apps packages/contracts/src packages/ui/src scripts .husky
-
Create root config files (use templates from references/config-templates.md):
-
Create scripts and runtime configs (use templates from references/scripts-templates.md):
-
Create non-negotiable packages (use templates from references/package-patterns.md):
-
Update CLAUDE.md (Read CLAUDE.md Guidance for the template)
-
Verify structure:
/js-monorepo add-package <name> [type]
When: Adding a new shared package to an existing monorepo.
Arguments:
<name> - Package name (e.g., config-eslint, config-tailwind, email)
[type] - Optional: source (no build, consume as TypeScript) or compiled (builds to dist). Default: source.
Steps:
-
Create package directory:
mkdir -p packages/<name>/src
-
Determine package type:
| Type | Build | Main | Types | Use Case |
|---|
source | noEmit: true | ./src/index.ts | ./src/index.ts | UI components, hooks, config |
compiled | tsc --build | ./dist/index.js | ./src/index.ts | Contracts, utilities shared with backend |
-
Create package files (use templates from references/package-patterns.md):
-
Wire into monorepo:
- Apps that need it: add
"@your-org/<name>": "workspace:*" to dependencies
- Run
pnpm install to link
-
Verify:
/js-monorepo review
When: Auditing an existing monorepo for issues, after setup, or during troubleshooting.
Steps:
-
Scan root config files:
-
Scan non-negotiable packages:
-
Scan standardized scripts across all packages:
-
Scan task pipeline in turbo.json:
-
Scan dependency management:
-
Scan bootstrap and pre-commit:
-
Scan CLAUDE.md (if exists):
-
Report findings with severity:
- CRITICAL - Missing non-negotiable packages, broken task pipeline, no catalogs
- WARNING - Missing .prettierignore/.gitignore, no CLAUDE.md guidance, incomplete scripts
- INFO - Missing optional config, style suggestions
CLAUDE.md Guidance
When /js-monorepo init runs or when this skill is used on an existing repo, update the project's CLAUDE.md with monorepo-specific context. Add or update these sections:
## Project Overview
- **Stack**: [describe apps - e.g., Next.js frontend + NestJS API]
- **Package Manager**: pnpm (workspace monorepo)
- **Build System**: Turborepo
## Repository Structure
[Include the actual monorepo structure with apps/ and packages/]
## Key Conventions
### Scripts
Standard scripts at root level (run via `pnpm <script>`):
| Script | Purpose |
|--------|---------|
| `pnpm dev` | Start all apps in dev mode |
| `pnpm build` | Build all packages (respects dependency graph) |
| `pnpm lint` | Lint all packages |
| `pnpm typecheck` | Type-check all packages |
| `pnpm check` | Full validation (format + lint + typecheck + build) |
| `pnpm fix` | Auto-fix formatting and lint issues |
| `pnpm test` | Run all tests |
| `pnpm bootstrap` | One-command setup for new developers |
### Imports
- Use `@your-org/contracts` for shared types and Zod schemas
- Use `@your-org/ui/components/ui/*` for shadcn primitives
- Use `@your-org/ui/components/patterns/*` for composed patterns
- Use `@your-org/ui/hooks/*` for shared hooks
- Use `@/` for app-internal absolute imports
### Packages
| Package | Purpose |
|---------|---------|
| `@your-org/contracts` | Shared types, Zod schemas, interfaces (domain-organized) |
| `@your-org/ui` | React components, hooks, patterns (fine-grained exports) |
### Adding Dependencies
- Internal packages: `"@your-org/contracts": "workspace:*"` in package.json
- External packages: Use `catalog:` protocol (versions defined in pnpm-workspace.yaml)
Checklist
For /js-monorepo init
For /js-monorepo add-package
For /js-monorepo review
Related Skills
/react-ui - React component creation, extraction, patterns, review. Use for UI concerns (shadcn primitives, forms, themes).
/nextjs-data - Next.js App Router data layer. Use for page creation, query layers, and SSR hydration.
Reference Files
- references/config-templates.md - Root config file templates (turbo, tsconfig, eslint, prettier, etc.)
- references/scripts-templates.md - Scripts, package.json, pre-commit, and bootstrap templates
- references/package-patterns.md - Package structure, standardized scripts, and export patterns
- references/shadcn-setup.md - shadcn/ui initialization, components.json, and monorepo wiring