Adding Packages

Overview

Shared packages live in packages/ and are consumed by apps via @hn-monorepo/{name}. Bun workspaces auto-discover packages, so no manual workspace registration is needed.

1. Create the Package Directory

Create packages/{name}/ with the following structure:

packages/{name}/
├── src/
│   └── index.ts          # Main entry point
├── package.json
├── tsconfig.json
└── README.md

2. Configure package.json

{
  "name": "@hn-monorepo/{name}",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts",
    "./*": "./src/*/index.ts"
  },
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "devDependencies": {
    "@hn-monorepo/config-typescript": "workspace:*",
    "typescript": "catalog:"
  }
}

Exports Field

The exports field maps import paths to source files. Define explicit subpath exports for organized packages:

{
  "exports": {
    ".": "./src/index.ts",
    "./components/*": "./src/components/*/index.ts",
    "./hooks": "./src/hooks/index.ts",
    "./utils": "./src/utils/index.ts"
  }
}

Consumers import via:

import { Button } from "@hn-monorepo/ui/components/button";
import { useAuth } from "@hn-monorepo/auth";

3. Configure TypeScript

Create tsconfig.json extending the shared config:

{
  "extends": "@hn-monorepo/config-typescript/base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

4. Auto-Discovery

Packages are auto-discovered via Bun workspaces defined in the root package.json:

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

No additional registration is needed. After creating the package directory with a valid package.json, run bun install to link it.

5. Use from Apps

Add the package as a dependency in consuming apps:

{
  "dependencies": {
    "@hn-monorepo/{name}": "workspace:*"
  }
}

Then import:

import { myUtility } from "@hn-monorepo/{name}";

6. Update Documentation

After creating the package:

1. Add to the root README.md package list
2. Add to the root CLAUDE.md architecture tree
3. Create a README.md for the package describing its purpose and API

Existing Packages

Package	Purpose
@hn-monorepo/ai	AI provider abstractions
@hn-monorepo/analytics	Analytics abstraction
@hn-monorepo/api	Shared API utilities
@hn-monorepo/auth	Convex auth provider pattern
@hn-monorepo/billing	Stripe billing patterns
@hn-monorepo/config	Shared env validation (t3-env)
@hn-monorepo/config-biome	Shared Biome config
@hn-monorepo/config-typescript	Shared TypeScript config
@hn-monorepo/convex-helpers	Convex utility helpers
@hn-monorepo/email	Email templates + sending (React Email + Nodemailer)
@hn-monorepo/i18n	Shared i18n (next-intl)
@hn-monorepo/monitoring	OTel + SigNoz error monitoring
@hn-monorepo/changelog	Changelog generation
@hn-monorepo/planex-cli	Planex CLI tool
@hn-monorepo/planex-engine	Core engine for AI blueprint generation
@hn-monorepo/security	Security utilities
@hn-monorepo/signage	Digital signage utilities
@hn-monorepo/shared	Shared utilities, hooks, and types
@hn-monorepo/storage	Storage utilities
@hn-monorepo/testing	Shared test config + fixtures
@hn-monorepo/ui	Shared UI components (shadcn/ui based)

Checklist

• Package directory created at packages/{name}/
• package.json with @hn-monorepo/{name} name and exports field
• tsconfig.json extending @hn-monorepo/config-typescript
• README.md documenting the package
• bun install run to link the package
• Added to root README.md package list
• Added to root CLAUDE.md architecture tree