js-monorepo

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

1. pnpm workspaces only - No yarn workspaces, no npm workspaces. pnpm is the package manager.
2. Turborepo for task orchestration - All cross-package scripts go through turbo.
3. Two non-negotiable packages - Every monorepo MUST have contracts and ui packages.
4. workspace:* protocol - Apps reference internal packages via "@your-org/contracts": "workspace:*".
5. pnpm catalogs for external deps - Define versions once in pnpm-workspace.yaml, reference via catalog: protocol.
6. Root owns tooling - ESLint, Prettier, TypeScript base config, Husky all live at the root.
7. Packages own their tsconfig - Each package extends tsconfig.base.json from root.
8. Standardized script names - All packages use the same turbo-compatible script names (Read references/package-patterns.md for the full script table).
9. 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

1. Read references/config-templates.md - Root config file templates
2. Read references/scripts-templates.md - Script and runtime config templates
3. Read references/package-patterns.md - Package structure, scripts, and guidance
4. 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:

1. Scaffold directory structure:

   mkdir -p apps packages/contracts/src packages/ui/src scripts .husky
   

2. Create root config files (use templates from references/config-templates.md):

   • pnpm-workspace.yaml - Workspace packages + dependency catalogs
   • turbo.json - Task pipeline with env vars and caching config
   • tsconfig.base.json - Shared TypeScript base (strict, verbatimModuleSyntax)
   • eslint.config.mjs - ESLint 9 flat config with projectService
   • prettier.config.mjs - Prettier with import sorting + Tailwind
   • .prettierignore - Ignore build artifacts, lockfiles, cache
   • .gitignore - Comprehensive monorepo ignores
   • .editorconfig - Editor consistency

3. Create scripts and runtime configs (use templates from references/scripts-templates.md):

   • package.json - Root with engines, scripts, devDependencies
   • .husky/pre-commit - Smart pre-commit hook
   • scripts/pre-commit-checks.sh - Pre-commit validation script (capture → fix → restage → validate)
   • scripts/bootstrap.sh - One-command developer setup

4. Create non-negotiable packages (use templates from references/package-patterns.md):

   • packages/contracts/ - Types, Zod schemas, shared interfaces
   • packages/ui/ - React components, hooks, utilities

5. Update CLAUDE.md (Read CLAUDE.md Guidance for the template)

6. Verify structure:

   • pnpm install succeeds
   • pnpm build succeeds (turbo)
   • pnpm check succeeds (format + lint + typecheck + build)

/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:

1. Create package directory:

   mkdir -p packages/<name>/src
   

2. 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

3. Create package files (use templates from references/package-patterns.md):

   • package.json - Name, exports, standardized scripts, dependencies (use catalog: for external deps)
   • tsconfig.json - Extends root tsconfig.base.json
   • src/index.ts - Barrel export

4. Wire into monorepo:

   • Apps that need it: add "@your-org/<name>": "workspace:*" to dependencies
   • Run pnpm install to link

5. Verify:

   • pnpm build passes with new package in the graph
   • Importing from the package works in consuming apps

/js-monorepo review

When: Auditing an existing monorepo for issues, after setup, or during troubleshooting.

Steps:

1. Scan root config files:

   • pnpm-workspace.yaml exists with apps/* + packages/* and catalogs
   • turbo.json exists with correct task dependencies, env vars, and outputLogs
   • tsconfig.base.json exists with strict mode and verbatimModuleSyntax
   • eslint.config.mjs exists with TypeScript projectService + allowDefaultProject
   • prettier.config.mjs exists with import sorting
   • .prettierignore exists (not formatting build artifacts)
   • .gitignore exists with monorepo patterns (.turbo, dist, .next, *.tsbuildinfo)
   • .editorconfig exists
   • .husky/pre-commit exists and calls pre-commit script

2. Scan non-negotiable packages:

   • packages/contracts/ exists with proper exports
   • packages/ui/ exists with fine-grained exports
   • Both have tsconfig.json extending root
   • Both have standardized scripts (lint, typecheck, validate, build/dev)

3. Scan standardized scripts across all packages:

   • All packages have lint, typecheck, validate scripts
   • Compiled packages have build and dev (watch) scripts
   • Source packages have dev (watch --noEmit) script
   • Root has all orchestration scripts (Read references/scripts-templates.md for expected scripts)

4. Scan task pipeline in turbo.json:

   • format task exists (no cache)
   • lint depends on ^format, has inputs and outputLogs: "errors-only"
   • typecheck depends on ^typecheck
   • build depends on ^build, validate, typecheck, has env for framework vars
   • dev is persistent, no cache, interruptible: true
   • globalEnv includes CI and NODE_ENV

5. Scan dependency management:

   • Apps use workspace:* protocol for internal packages
   • External deps use catalog: protocol where possible
   • Catalogs defined in pnpm-workspace.yaml
   • @your-org/* import paths resolve

6. Scan bootstrap and pre-commit:

   • scripts/bootstrap.sh exists and is executable
   • Root package.json has "bootstrap" script
   • Bootstrap covers: install, docker (if applicable), db setup (if applicable)
   • Pre-commit captures staged files, restages after fix, validates with lint + typecheck

7. Scan CLAUDE.md (if exists):

   • Documents monorepo structure
   • Documents script conventions
   • Documents import conventions (@your-org/* paths)
   • Documents package consumption patterns

8. 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

• All root config files created (including .prettierignore, .gitignore)
• contracts and ui packages created with standardized scripts
• Bootstrap and pre-commit scripts created
• CLAUDE.md updated with monorepo conventions
• pnpm install succeeds
• pnpm check passes

For /js-monorepo add-package

• Package directory and files created
• Correct type (source vs compiled)
• Standardized scripts included (lint, typecheck, validate, build/dev)
• tsconfig extends root
• Uses catalog: for external deps
• Consuming apps wired up
• Build passes

For /js-monorepo review

• All config files scanned (including .prettierignore, .gitignore)
• Non-negotiable packages verified with standardized scripts
• Task pipeline validated (env, inputs, outputLogs)
• Dependency management checked (catalogs, workspace protocol)
• Pre-commit strategy confirmed
• CLAUDE.md has monorepo guidance (if exists)
• Report generated with severity levels

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