Add Package Rapid

Rapidly add and configure new packages or dependencies in monorepo workspaces with proper directory structure, build configuration, and workspace integration.

When to Use This Command

Run this command when...

• You need to add a new package or library to a monorepo workspace with all the required scaffolding
• A shared library needs to be created and wired into the workspace dependency graph
• You want to add a new microservice, tool, or application package following existing workspace conventions
• A new package needs TypeScript configuration, build scripts, linting, and test setup matching the workspace standard
• You need to scaffold a package with proper exports, entry points, and inter-package dependencies

Quick Start

Copy
# .claude/commands/add-package-rapid.md
---
name: Add Package Rapid
description: Add packages to monorepo workspaces with full configuration
command: true
---
Add package: $ARGUMENTS

1. Parse package name and type from arguments
2. Validate naming conventions and check for conflicts
3. Create package directory with standard structure
4. Configure TypeScript, build, test, and lint settings
5. Wire into workspace and update dependency graph

Copy
# Invoke the command
claude "/add-package-rapid @myapp/email-service library"

# Expected output
# > Validating package name: @myapp/email-service
# >   Type: library | Location: packages/email-service
# >   No naming conflicts found
# > Creating package structure...
# >   packages/email-service/
# >     package.json (workspace config)
# >     tsconfig.json (extends root)
# >     src/index.ts (entry point)
# >     src/__tests__/index.test.ts
# >     README.md
# > Configuring build...
# >   Added to workspace packages array
# >   Build target: ESM + CJS dual output
# >   Test config: Jest (matching workspace)
# > Installing dependencies...
# >   Linked workspace dependency graph
# > Package @myapp/email-service ready for development.

Core Concepts

Concept	Description
Workspace Integration	Creates packages that are immediately discoverable and linkable within the monorepo
Convention Detection	Reads existing package configurations to replicate naming, build, and test patterns
Type-Aware Scaffolding	Different structures for libraries, applications, tools, services, and component packages
Dual Output	Configures both ESM and CJS builds when the workspace standard supports both module systems
Dependency Graph Wiring	Updates workspace configuration and root-level dependency management

Package Scaffolding by Type
=============================

  Type          Structure               Build Output
  ----------   ----------------------  ----------------
  library      src/ + tests/ + index   ESM + CJS + types
  application  src/ + pages/ + config  Bundle (app)
  service      src/ + routes/ + tests  Node.js bundle
  tool         src/ + bin/ + tests     CLI executable
  component    src/ + stories/ + test  ESM + types

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Package name and optional type	none	"@myapp/utils library"	Yes
package_type	Type of package to create	library	"service", "tool", "application"	No
workspace_root	Root directory of the monorepo	auto-detect	"packages/"	No
template_package	Existing package to use as template	auto-detect	"packages/core"	No
dependencies	Initial dependencies to install	none	"zod, winston"	No

Best Practices

1. Follow workspace naming conventions -- Use the same scope prefix and naming style as existing packages. Consistency in naming makes the monorepo navigable.

2. Start with the correct package type -- Library, service, and application types produce different scaffolding. Choosing the right type upfront avoids restructuring later.

3. Reference an existing package as template -- Use template_package to point at a well-configured existing package so the new one inherits the exact build, lint, and test setup.

4. Add inter-package dependencies explicitly -- After creating the package, declare dependencies on other workspace packages in package.json to establish the dependency graph correctly.

5. Verify the build and test pipeline -- Run the workspace build and test commands immediately after creation to confirm the new package integrates correctly with CI.

Common Issues

Workspace not detecting new package: Some monorepo tools (Turborepo, Nx) require explicit package registration or cache clearing. Run turbo run build --force or clear the .nx cache after adding.

TypeScript path resolution fails: If the new package cannot import from other workspace packages, verify that tsconfig.json references and path mappings include the new package location.

Build order incorrect: The new package may need to build after its workspace dependencies. Ensure the build system (Turborepo, Lerna) correctly orders builds based on the inter-package dependency graph.