playbooks

home / skills / shipshitdev / library / package-architect

package-architect skill

/bundles/workspace/skills/package-architect

This skill helps you design and maintain TypeScript packages in a monorepo with clear exports and robust build configuration.

npx playbooks add skill shipshitdev/library --skill package-architect

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.3 KB
---
name: package-architect
description: Design and maintain TypeScript packages in a monorepo, including exports and build configuration.
---

# Package Architect

You design reusable TypeScript packages in monorepos (Bun, pnpm, or npm workspaces).

## When to Use

- Creating new packages or restructuring monorepo packages
- Defining package.json exports
- Setting up tsconfig references

## Core Principles

- Single responsibility per package.
- Stable public APIs with clear exports.
- Avoid inline interfaces; centralize types.
- Keep build outputs separated from sources.

## Package Structure (Example)

```
packages/
  utils/
    src/
    package.json
    tsconfig.json
  api-client/
    src/
    package.json
    tsconfig.json
```

## Exports Pattern (Example)

```json
{
  "name": "@scope/utils",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
```

## TypeScript References

- Use project references for inter-package dependencies.
- Prefer path aliases for local dev imports.
- Keep tsconfig base shared across packages.

## Checklist

- Exports map matches intended public API
- Types build alongside JS output
- No circular dependencies
- Consistent lint and tsconfig settings

Overview

This skill helps design and maintain TypeScript packages within monorepos (Bun, pnpm, or npm workspaces). It focuses on package boundaries, exports, build configuration, and TypeScript project references to produce stable, reusable packages.

How this skill works

The skill inspects package layout, package.json exports, TypeScript configs, and build outputs to validate public APIs and cross-package dependencies. It suggests changes to exports maps, tsconfig references, and build pipelines to ensure types are emitted, outputs are isolated, and no circular dependencies exist.

When to use it

  • Creating new packages inside a monorepo
  • Refactoring or splitting an existing package into single-responsibility modules
  • Defining or tightening package.json exports and types fields
  • Setting up or troubleshooting TypeScript project references and path aliases
  • Preparing packages for consistent builds and publishing

Best practices

  • Model each package around a single responsibility and a clear public API
  • Declare explicit exports in package.json to control surface area and enable conditional exports
  • Emit types alongside JS and ensure types paths in exports map are correct
  • Use TypeScript project references for inter-package compilation and path aliases for local development
  • Keep build outputs in a separate dist (or build) folder and exclude outputs from source control
  • Enforce consistent lint, formatting, and shared tsconfig/base settings across packages

Example use cases

  • Add a new @scope/logger package with its own tsconfig and export map for use across services
  • Refactor a large utilities package into smaller single-purpose packages and update project references
  • Diagnose missing types in a consumer package by verifying types fields and build outputs
  • Convert relative imports to path aliases and add project references to speed incremental builds
  • Lock down public API surface by replacing wildcard exports with an explicit exports map

FAQ

How should I structure exports to publish both ESM and CJS?

Provide conditional exports in package.json with import/module/require targets and point types to a single emitted .d.ts entry. Keep build outputs per format in distinct files referenced by the exports map.

When should I use project references vs path aliases?

Use project references to enable incremental, type-checked builds across packages. Use path aliases for convenient local imports during development. Combine both: aliases for source-level imports and references for compilation.