nx-workspace-architecture

Guide structuring new features in Nx workspaces. Use when user asks about creating libraries, organizing code, or where to place new features.

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/nx-workspace-architecture-juristr-tusky

SKILL.md

Nx Workspace Architecture

Core Principles

Domain over Technical - organize by business domains (products, orders, checkout), not technical types (components, services)
Thin App Shell - apps are deployment containers; business logic lives in libs
Explicit Boundaries - use Nx projects to enforce separation, not just folders

Library Types

Prefix	Purpose	Can Import
`feat-*`	Smart components, pages, business logic	feat, ui, data-access, util
`ui-*`	Presentational/dumb components	ui, util
`data-access`	API calls, state management	data-access, util
`util`	Pure functions, helpers, types	util only

Folder Structure

packages/
├── {domain}/           # e.g. products, orders, checkout
│   ├── data-access/
│   ├── feat-{name}/
│   ├── ui-{name}/
│   └── util/
└── shared/             # cross-domain utilities

Tagging Strategy

Add to project.json:

scope:{domain} - vertical boundary (products, orders, shared)
type:{library-type} - horizontal layer (feature, ui, data-access, util)

Decision Flow

When user wants to add new functionality:

Identify domain - which business area does it belong to?
Determine library type:
- Has routing/pages? → feat-*
- Purely visual component? → ui-*
- API/state logic? → data-access
- Pure utilities? → util
Check existing libs - can it extend an existing library?
Create new lib only if needed for clear separation

When to Split Libraries

Split when you observe:

Frequent cross-library changes for single features
Circular dependencies emerging
Unclear ownership between teams
Single lib growing too large (>20 files is a smell)

Generator Commands

Use the nx-generators skill.