Adding a Package

How to add a new shared package to the monorepo.

1. Create the directory


mkdir -p packages/my-package

2. Create `package.json`


{
  "name": "@numa/my-package",
  "private": true,
  "exports": {
    ".": "./src/index.ts"
  },
  "dependencies": {},
  "devDependencies": {
    "@numa/typescript-config": "workspace:*",
    "typescript": "^5"
  }
}

3. Create `tsconfig.json`


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

4. Add to consuming apps


pnpm --filter @numa/energy add @numa/my-package@workspace:*

5. Add to `transpilePackages`

In the consuming app’s next.config.ts:


transpilePackages: ["@numa/my-package"],

6. Install and build


pnpm install
pnpm build

Important rules

Sub-path exports

Every import path used by consumers must be in the exports field:


{
  "exports": {
    ".": "./src/index.ts",
    "./helpers": "./src/helpers.ts",
    "./types": "./src/types.ts"
  }
}

No `@/` imports in packages

Inside packages/*, always use @numa/* imports. The @/ alias only works inside apps/*:


// Inside packages — correct
import { PLATFORMS } from "@numa/config/platforms";
 
// Inside packages — wrong (will break)
import { PLATFORMS } from "@/config/platforms";

Direct dependencies required

Every import in a package must correspond to a dependency in that package’s package.json. pnpm’s strict isolation means you can’t rely on hoisted dependencies:


# Add an external dependency
cd packages/my-package
pnpm add some-library
 
# Add a workspace dependency
pnpm add @numa/utils@workspace:*

Avoid circular dependencies

If package A needs something from package B and B already depends on A, use dependency inversion:


// Instead of importing a component from @numa/ui in @numa/providers:
export function MyProvider({ children, fallback }: { children: ReactNode; fallback?: ReactNode }) {
  return isLoading ? fallback : children;
}
 
// Then in the app, pass the component:
<MyProvider fallback={<LoadingComponent />}>
  {children}
</MyProvider>

Type declarations

If your package uses React types, add them as dev dependencies:


pnpm add -D @types/react @types/node