# Adding New Libraries

> **Canonical reference:** the full, maintained walkthrough lives at
> **[Adding a New Library](../reference/adding-new-library.md)**. 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](../reference/adding-new-library.md) 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](../../docs-center/systems/index.html) 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._