nx

Instruction file imported from wghglory/ngx-lift-workspace (.cursor/rules/nx.mdc). Copyright stays with the author.

Nx Workspace Guidelines

Project Structure

• Libraries: Place reusable code in libs/ directory

  • libs/ngx-lift/: Core Angular utilities library (RxJS operators, signals, pipes, validators)
  • libs/clr-lift/: Clarity Design System component library (depends on ngx-lift)

• Applications: Place applications in apps/ directory

  • apps/demo/: Demo application showcasing both libraries
  • apps/demo-e2e/: E2E tests for demo app

• Tools: Place build tools and scripts in tools/ directory

  • tools/vitest/: Vitest configuration utilities
  • tools/eslint-plugin/: Custom ESLint rules

Project Configuration

• project.json: Each project has a project.json with targets
• tsconfig.json: TypeScript configuration per project
• vite.config.mts: Vitest configuration for testing (libraries)
• ng-package.json: Angular packaging configuration (libraries)
• eslint.config.mjs: ESLint configuration per project

Nx Commands

• Build: npx nx build [project-name]
• Test: npx nx test [project-name] (not nx test)
• Lint: npx nx lint [project-name]
• Serve: npx nx serve [project-name]
• E2E: npx nx e2e [e2e-project-name]
• Graph: npx nx graph (visualize project dependencies)

Dependency Management

• Module Boundaries: Respect Nx project boundaries

  • Configured in eslint.config.mjs with @nx/enforce-module-boundaries
  • No circular dependencies allowed

• Tags: Use tags to organize projects

  • Define in project.json or nx.json
  • Enforce dependency rules based on tags

• Imports: Libraries are local packages in this monorepo

  // Import from ngx-lift library
  import {createAsyncState, poll} from 'ngx-lift';
  
  // Import from clr-lift library
  import {AlertComponent, ToastService} from 'clr-lift';
  
  // Path mappings defined in tsconfig.base.json

Code Generation

• Generators: Use Nx generators for consistent structure

  npx nx generate @nx/angular:library my-lib
  npx nx generate @nx/angular:component my-component --project=my-lib

• Schematic Options: Configure default options in nx.json

  "generators": {
    "@nx/angular:component": {
      "style": "scss"
    }
  }

Build Configuration

• Build Targets: Configure build targets in project.json

• Dependencies: Use dependsOn to specify build dependencies

  "dependsOn": ["^build"]

• Inputs: Define inputs for caching

  "inputs": ["production", "^production"]

Testing Configuration

• Vitest: Configure Vitest in vite.config.mts

  • Test environment: jsdom
  • Setup files: src/test-setup.ts
  • Uses @analogjs/vitest-angular for Angular component testing
  • Transform configuration for TypeScript, HTML, and SVG files

• Playwright: Configure E2E tests in playwright.config.ts

  • Use nxE2EPreset from @nx/playwright
  • Configure web server for local development

Caching

• Build Cache: Nx caches build outputs

  • Use nx reset to clear cache
  • Cache stored in .nx/cache

• Test Cache: Tests are cached based on inputs

  • Only re-run tests when inputs change

Affected Commands

• Affected Graph: npx nx affected:graph
• Affected Test: npx nx affected -t test
• Affected Build: npx nx affected -t build
• Affected Lint: npx nx affected -t lint

Workspace Configuration

• nx.json: Workspace-level configuration

  • Plugins configuration
  • Target defaults
  • Generators defaults

• tsconfig.base.json: Base TypeScript configuration

  • Path mappings
  • Compiler options

Library Publishing

• Build Libraries: npm run build:libs (builds both ngx-lift and clr-lift)
• Build Individual: npm run build:ngx or npm run build:clr
• Watch Mode: npm run watch:ngx or npm run watch:clr
• Publish: Automated via GitHub Actions or manual npm publish
  • Configuration in ng-package.json per library
  • Output in dist/libs/[library-name]
  • Version management via nx release

Best Practices

• Project Boundaries: Always respect module boundaries
• Dependency Rules: Configure and follow dependency rules
• Code Organization: Organize code by feature/domain
• Shared Code: Extract shared code to libraries
• Testing: Write tests for all libraries
• Documentation: Document library APIs and usage

Troubleshooting

• Cache Issues: Clear cache with nx reset
• Dependency Issues: Check nx graph for circular dependencies
• Build Issues: Ensure all dependencies are built first
• Path Resolution: Verify tsconfig.base.json paths

Code Review Checklist - Nx Workspace

Use this checklist when reviewing workspace structure changes:

• Respects module boundaries
• No circular dependencies