Nx Workspace Guidelines

---
alwaysApply: true
---

## 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

  ```typescript
  // 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

  ```bash
  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`
  ```json
  "generators": {
    "@nx/angular:component": {
      "style": "scss"
    }
  }
  ```

### Build Configuration

- **Build Targets**: Configure build targets in `project.json`
- **Dependencies**: Use `dependsOn` to specify build dependencies

  ```json
  "dependsOn": ["^build"]
  ```

- **Inputs**: Define inputs for caching
  ```json
  "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