monorepo-workspace-rename

name	monorepo-workspace-rename
description	Rename a workspace package (e.g., `@org/jw-types` → `@org/core-types`) across a monorepo without breaking consumers. The pattern: use codemod/IDE refactor across the monorepo, update root `package.json` workspaces + tsconfig paths, version-bump, publish to local registry, re-run full monorepo build. Use when consolidating packages or rebranding.

Monorepo Workspace Rename

When you need to rename a workspace package (e.g., @ashbi/jw-types → @ashbi/core-types), there are many files to touch. This skill covers the standard recipe.

The 6-Point Plan

1. Update package.json name field in the workspace's own directory
2. Update root package.json workspaces if it has explicit entries
3. Update root tsconfig.json paths and references
4. Find-and-replace import paths in all consumers
5. Update CI workflows that reference the package name
6. Bump version of the renamed package (so consumers can see "this changed")

Per-File Changes

1. Workspace's own package.json

{
  "name": "@ashbi/core-types",  // was: "@ashbi/jw-types"
  "version": "2.0.0",            // bump the major
  ...
}

2. Root package.json workspaces

{
  "workspaces": [
    "packages/*",  // usually pattern-based, no change
    "apps/*"
  ]
}

Pattern-based workspaces don't need changes. Explicit array workspaces do:

{
  "workspaces": [
    "packages/core-types",  // was: "packages/jw-types"
    ...
  ]
}

3. Root tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@ashbi/core-types": ["packages/core-types/src"],  // was: jw-types
      "@ashbi/core-types/*": ["packages/core-types/src/*"]
    }
  },
  "references": [
    { "path": "./packages/core-types" },  // was: jw-types
    ...
  ]
}

4. Import paths in consumers

// Before
import { User } from '@ashbi/jw-types';

// After
import { User } from '@ashbi/core-types';

Find all files:

grep -rl '@ashbi/jw-types' --include="*.ts" --include="*.tsx" .

Replace all (use IDE refactor or find ... -exec sed -i):

find . -type f \( -name '*.ts' -o -name '*.tsx' \) \
  -exec sed -i 's/@ashbi\/jw-types/@ashbi\/core-types/g' {} \;

5. CI workflows

# .github/workflows/ci.yml
- working-directory: packages/jw-types  # was: this name
  run: npm run build

6. Bump version

{
  "version": "2.0.0"  // was: "1.5.0" - bump major to signal breaking change
}

Multi-Repo vs Single-Repo

• Single repo: the above recipe is enough. Commit all changes in one PR.
• Multi-repo (package published to npm): you also need to:
  • Update the published version on npm
  • Coordinate with consumers (they need to bump their dep)
  • Consider a deprecation period (publish the old name as an alias)

For the multi-repo case, do the rename in two phases:

1. Phase 1: publish @ashbi/core-types@2.0.0 alongside the old name (npm supports publishConfig.alias)
2. Phase 2: after consumers migrate, deprecate the old name

Verification

After the rename:

1. Run the full monorepo build: npm run build
2. Run the test suite: npm test
3. Grep for any leftover references: grep -r '@ashbi/jw-types' . (should be empty except in old commits)
4. Update any docs that reference the old name

Common Pitfalls

1. Forgetting root tsconfig.json paths — TypeScript can't resolve the new name even if package.json is correct
2. Missing .eslintrc.json overrides — some repos have per-workspace ESLint config that needs updating
3. Docker image references — if the workspace has its own Dockerfile, the COPY paths need updating
4. Lockfile conflicts — if the renamed package was already published under the old name, the lockfile can have both. Use npm install --save-exact to force the new name.

Related Skills & Chains

• monorepo-ci-matrix — If the rename breaks the CI matrix, this skill has the patterns to fix it
• lockfile-regen — Rename usually requires lockfile regen