nx-workspace-architecture

juristr's avatarfrom juristr

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

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 10, 2025
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides expert guidance on architecting and structuring Nx workspaces using domain-driven design principles. It helps developers implement a scalable monorepo strategy by defining clear library boundaries, organizing code by business domains, and maintaining a clean separation between UI, logic, and data layers.

Use Cases

  • New Feature Planning: Determining the optimal location for new functionality and deciding whether to create a new library or extend an existing one.
  • Monorepo Organization: Structuring large-scale codebases into domain-specific folders to improve maintainability and team ownership.
  • Enforcing Code Boundaries: Implementing tagging strategies and library types (feat, ui, data-access, util) to prevent circular dependencies and architectural erosion.
  • Refactoring Guidance: Identifying when to split oversized libraries into smaller, more manageable modules based on file count and responsibility.
namenx-workspace-architecture
descriptionGuide structuring new features in Nx workspaces. Use when user asks about creating libraries, organizing code, or where to place new features.
allowed-toolsBash, Glob, Grep, Read

Nx Workspace Architecture

Core Principles

  1. Domain over Technical - organize by business domains (products, orders, checkout), not technical types (components, services)
  2. Thin App Shell - apps are deployment containers; business logic lives in libs
  3. 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:

  1. Identify domain - which business area does it belong to?
  2. Determine library type:
    • Has routing/pages? → feat-*
    • Purely visual component? → ui-*
    • API/state logic? → data-access
    • Pure utilities? → util
  3. Check existing libs - can it extend an existing library?
  4. 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.