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

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:

   code

   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:

   code

   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