Disciplines · Guides

Adding New Libraries

The Oshun monorepo is an Nx workspace of ~2,500 projects.

3sections2 minread
Markdown source
On this page

Canonical reference: the full, maintained walkthrough lives at Adding a New Library. This page is a stable entry point that orients you and links onward — it deliberately does not duplicate the step-by-step detail, so there is a single source of truth to keep current.

Why this page exists#

The Oshun monorepo is an Nx workspace of ~2,500 projects. A new library is not just a folder of TypeScript — it is a tracked Nx project with a project.json, a package.json, a tsconfig.json, a path mapping in tsconfig.base.json, and a set of tags (scope:*, layer:*, type:*) that the dependency graph, the lint boundaries, and the documentation center's entity catalog all read. Getting those wiring details right up front is what makes a library composable, buildable, and discoverable; getting them wrong produces a project that compiles locally but breaks nx affected, the module-boundary lint, or the freshness gate.

What the canonical guide covers#

The reference guide walks the whole path:

  • Where it goes — choosing between libs/shared/ (cross-domain utilities), libs/contracts/ (API contracts, event schemas, shared types), and libs/{domain}/ (domain-specific code), and the tag each location implies.
  • Scaffolding it — generating the project with the Nx generator (preferred) or by hand, and the four files every library must carry (project.json, package.json, tsconfig.json, plus the tsconfig.base.json path mapping).
  • Configuration templates — buildable-vs-non-buildable tsconfig.lib.json setup, the catalog: dependency convention from pnpm-workspace.yaml, and the build/test/lint/typecheck targets.
  • Testing setup — the Vitest project wiring and a first domain-correctness test, not just a smoke test.
  • Conventions, best practices, and troubleshooting — the module-boundary rules, naming, and the common failure modes (dist-pointing package.json, rootDir/TS6059 for buildable libs, missing path map).

When to use it#

Reach for the canonical guide whenever you are creating a new libs/* project, splitting an oversized library, or extracting shared code out of an app. If you only need to find an existing library, browse the systems entity catalog instead — every tracked project already has a code-linked node there.

This consolidated stub preserves the historical docs/guides/ entry point so inbound links keep resolving, while the maintained content lives in one place.