skills/plugins/suaveplan-dependency-management/skills/dependency-management/SKILL.md

name, description

name	description
dependency-management	Bun monorepo dependency management with version overrides, catalogs, workspace protocol, tree-shaking configuration, and React version conflict resolution

Dependency Management

Use this skill when adding dependencies, resolving version conflicts, configuring tree-shaking, or troubleshooting build issues related to package versions in the Suaveplan monorepo.

Bun Monorepo Dependency Management

Critical Rules

• Always use exact versions in overrides and catalog (not ranges like ^19.0.0)
• Use Bun's overrides field (NOT resolutions -- that's npm/yarn)
• Bun only supports top-level overrides (no nested overrides)

Example Configuration

{
  "overrides": {
    "react": "19.0.0",
    "react-dom": "19.0.0"
  },
  "workspaces": {
    "catalog": {
      "react": "19.0.0",
      "react-dom": "19.0.0"
    }
  }
}

Nuclear Clean (Required After Override Changes)

After changing overrides or catalog, do a complete nuclear clean:

rm -rf node_modules bun.lockb
find . -type d -name "node_modules" -exec rm -rf {} +
bun install --force

Verify Single Version

find . -path "*/node_modules/react/package.json" -exec grep "version" {} \; | sort -u
# Should show only ONE version

Check Framework Dependencies First

Before using any library:

1. Review package.json for existing dependencies
2. Follow existing import patterns in the package
3. Use workspace protocol (workspace:*) for internal deps
4. Use Bun catalogs for centralized version management

Workspace Protocol

Internal package dependencies use workspace:*:

{
  "dependencies": {
    "@suaveplan/core": "workspace:*",
    "@suaveplan/types": "workspace:*"
  }
}

Bun Workspaces

Defined in root package.json:

{
  "workspaces": ["packages/*", "apps/*"]
}

Bun Catalogs

Centralized dependency versions in root package.json:

{
  "catalogs": {
    "react": "^18.2.0",
    "typescript": "^5.3.0",
    "vitest": "^1.0.0"
  }
}

Use in packages:

{
  "dependencies": {
    "react": "catalog:react",
    "typescript": "catalog:build"
  }
}

Tree-Shaking Requirement

All library packages MUST declare side effects.

Pure Libraries

{
  "name": "@suaveplan/package-name",
  "type": "module",
  "sideEffects": false,
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    }
  }
}

Packages with CSS/Styles

{
  "sideEffects": ["**/*.css", "**/*.scss"]
}

Verification Checklist

Verify no actual side effects in entry points:

• No top-level function calls
• No global object mutations
• No immediate IIFEs
• Only export statements allowed

Required for optimal bundle sizes (30-50% reduction).

Troubleshooting: React Version Conflicts

Symptoms

• Error: Minified React error #31
• TypeError: Cannot read properties of null (reading 'useContext')
• Build fails during static page generation

Root Cause

Multiple React versions in monorepo.

Solution

# 1. Add exact version overrides to root package.json
# {
#   "overrides": {
#     "react": "19.0.0",
#     "react-dom": "19.0.0",
#     "@types/react": "19.0.0",
#     "@types/react-dom": "19.0.0"
#   }
# }

# 2. Update catalog to match (exact versions, no ^)
# {
#   "workspaces": {
#     "catalog": {
#       "react": "19.0.0",
#       "react-dom": "19.0.0"
#     }
#   }
# }

# 3. Nuclear clean install (REQUIRED!)
rm -rf node_modules bun.lockb
find . -type d -name "node_modules" -exec rm -rf {} +
bun install --force

# 4. Verify single React version
find . -path "*/node_modules/react/package.json" -exec grep version {} \; | sort -u
# Should show only ONE version

Key Points

• Use Bun overrides (NOT resolutions)
• Use exact versions (no ^ or ~)
• Complete clean install is REQUIRED
• Verify workspace catalog matches overrides