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.
1---2name: nx-workspace-architecture3description: Guide structuring new features in Nx workspaces. Use when user asks about creating libraries, organizing code, or where to place new features.4---5
6# Nx Workspace Architecture
7
8## Core Principles
9
101. **Domain over Technical** - organize by business domains (products, orders, checkout), not technical types (components, services)
112. **Thin App Shell** - apps are deployment containers; business logic lives in libs
123. **Explicit Boundaries** - use Nx projects to enforce separation, not just folders
13
14## Library Types
15
16| Prefix | Purpose | Can Import |
17| ------------- | --------------------------------------- | --------------------------- |
18| `feat-*` | Smart components, pages, business logic | feat, ui, data-access, util |
19| `ui-*` | Presentational/dumb components | ui, util |
20| `data-access` | API calls, state management | data-access, util |
21| `util` | Pure functions, helpers, types | util only |
22
23## Folder Structure
24
25```
26packages/
27├── {domain}/ # e.g. products, orders, checkout
28│ ├── data-access/
29│ ├── feat-{name}/
30│ ├── ui-{name}/
31│ └── util/
32└── shared/ # cross-domain utilities
33```
34
35## Tagging Strategy
36
37Add to project.json:
38
39- `scope:{domain}` - vertical boundary (products, orders, shared)
40- `type:{library-type}` - horizontal layer (feature, ui, data-access, util)
41
42## Decision Flow
43
44When user wants to add new functionality:
45
461. **Identify domain** - which business area does it belong to?
472. **Determine library type**:
48 - Has routing/pages? → `feat-*`
49 - Purely visual component? → `ui-*`
50 - API/state logic? → `data-access`
51 - Pure utilities? → `util`
523. **Check existing libs** - can it extend an existing library?
534. **Create new lib only if** needed for clear separation
54
55## When to Split Libraries
56
57Split when you observe:
58
59- Frequent cross-library changes for single features
60- Circular dependencies emerging
61- Unclear ownership between teams
62- Single lib growing too large (>20 files is a smell)
63
64## Generator Commands
65
66Use the nx-generators skill.
majiayu000