shipshitdev/package-architect

Package Architect

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)

{
  "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