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.
When & Why to Use This Skill
This Claude skill provides expert guidance on structuring Nx workspaces using Domain-Driven Design (DDD) principles. It helps developers maintain scalable monorepos by organizing code into modular libraries, enforcing explicit architectural boundaries, and defining clear roles for features, UI components, data access, and utilities.
Use Cases
- Case 1: Determining the correct library type (feat, ui, data-access, or util) when adding new functionality to an Nx workspace.
- Case 2: Refactoring a monolithic application into a domain-based folder structure to improve code ownership and maintainability.
- Case 3: Establishing tagging strategies in project.json to enforce horizontal and vertical architectural boundaries between different business domains.
- Case 4: Deciding when to split existing libraries to prevent circular dependencies and manage growing codebases effectively.
| name | nx-workspace-architecture |
|---|---|
| description | Guide structuring new features in Nx workspaces. Use when user asks about creating libraries, organizing code, or where to place new features. |
| allowed-tools | Bash, Glob, Grep, Read |
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
- Has routing/pages? →
- 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.