@smartsoft001-mobilems/claude-plugins 2.67.0 → 2.69.0

package/plugins/flow-legacy/skills/nx-conventions/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: nx-conventions
+description: Nx 14 monorepo patterns with @nrwl/* packages, workspace organization, and build conventions
+---
+
+# Nx 14 Conventions (Legacy)
+
+This skill provides guidance on Nx 14 monorepo patterns for legacy projects using `@nrwl/*` packages.
+
+## CRITICAL: Nx 14 vs Modern Nx
+
+| Feature | Nx 14 (Legacy) | Nx 21+ (Modern) |
+|---------|---------------|-----------------|
+| Packages | `@nrwl/*` | `@nx/*` |
+| Node.js | 18.x | 20.x / 22.x |
+| Angular | 14.x | 20.x |
+| Config | `workspace.json` or `project.json` | `project.json` |
+
+## 1. Workspace Structure
+
+```
+/
+├── apps/
+│   ├── web/              # Main Angular 14 application
+│   └── web-e2e/          # Cypress E2E tests
+├── libs/
+│   └── shared/
+│       └── angular/      # Shared Angular library
+├── tools/
+│   ├── specs/            # Project specifications
+│   └── mockups/          # Design mockups
+├── nx.json               # Nx workspace configuration
+├── tsconfig.base.json    # Base TypeScript config
+└── package.json
+```
+
+## 2. Project Naming
+
+| Type                | Pattern                  | Example                        |
+| ------------------- | ------------------------ | ------------------------------ |
+| Apps                | `{name}`                 | `web`, `api`                   |
+| E2E                 | `{app}-e2e`              | `web-e2e`                      |
+| Domain libs         | `{domain}-domain`        | `museum-objects-domain`        |
+| Angular libs        | `{domain}-shell-angular` | `museum-objects-shell-angular` |
+| Shared angular libs | `shared-angular`         | `shared-angular`               |
+
+## 3. Common Nx 14 Commands
+
+### Development
+
+```bash
+# Serve application
+nx serve web
+
+# Serve with specific configuration
+nx serve web --configuration=development
+
+# Build application
+nx build web
+
+# Build for production
+nx build web --configuration=production
+```
+
+### Testing
+
+```bash
+# Run unit tests
+nx test web
+nx test shared-angular
+
+# Run tests with coverage
+nx test web --coverage
+
+# Run tests in watch mode
+nx test web --watch
+
+# Run E2E tests
+nx e2e web-e2e
+
+# Open Cypress
+nx open-cypress web-e2e
+```
+
+### Linting
+
+```bash
+# Lint project
+nx lint web
+nx lint shared-angular
+
+# Lint all affected projects
+nx affected --target=lint
+```
+
+### Building
+
+```bash
+# Build single project
+nx build web
+
+# Build affected projects
+nx affected --target=build
+
+# Show dependency graph
+nx graph
+```
+
+## 4. Affected Commands
+
+Run tasks only on changed projects:
+
+```bash
+# Test affected
+nx affected --target=test
+
+# Lint affected
+nx affected --target=lint
+
+# Build affected
+nx affected --target=build
+
+# Specify base branch
+nx affected --target=test --base=main
+```
+
+## 5. Project Configuration (Nx 14)
+
+### project.json (Nx 14 format)
+
+```json
+{
+  "name": "web",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "application",
+  "sourceRoot": "apps/web/src",
+  "prefix": "app",
+  "targets": {
+    "build": {
+      "executor": "@angular-devkit/build-angular:browser",
+      "options": {
+        "outputPath": "dist/apps/web",
+        "index": "apps/web/src/index.html",
+        "main": "apps/web/src/main.ts",
+        "polyfills": "apps/web/src/polyfills.ts",
+        "tsConfig": "apps/web/tsconfig.app.json",
+        "assets": ["apps/web/src/favicon.ico", "apps/web/src/assets"],
+        "styles": ["apps/web/src/styles.scss"],
+        "scripts": []
+      },
+      "configurations": {
+        "production": {
+          "budgets": [
+            {
+              "type": "initial",
+              "maximumWarning": "2MB",
+              "maximumError": "4MB"
+            }
+          ],
+          "outputHashing": "all",
+          "optimization": true
+        },
+        "development": {
+          "buildOptimizer": false,
+          "optimization": false,
+          "vendorChunk": true,
+          "extractLicenses": false,
+          "sourceMap": true
+        }
+      },
+      "defaultConfiguration": "development"
+    },
+    "serve": {
+      "executor": "@angular-devkit/build-angular:dev-server",
+      "options": {
+        "browserTarget": "web:build",
+        "port": 4200
+      },
+      "configurations": {
+        "production": {
+          "browserTarget": "web:build:production"
+        },
+        "development": {
+          "browserTarget": "web:build:development"
+        }
+      },
+      "defaultConfiguration": "development"
+    },
+    "test": {
+      "executor": "@nrwl/jest:jest",
+      "options": {
+        "jestConfig": "apps/web/jest.config.ts",
+        "passWithNoTests": true
+      },
+      "outputs": ["{workspaceRoot}/coverage/apps/web"]
+    },
+    "lint": {
+      "executor": "@nrwl/linter:eslint",
+      "options": {
+        "lintFilePatterns": [
+          "apps/web/src/**/*.ts",
+          "apps/web/src/**/*.html"
+        ]
+      }
+    }
+  }
+}
+```
+
+## 6. Path Mappings
+
+In `tsconfig.base.json`:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@shared/angular": ["libs/shared/angular/src/index.ts"],
+      "@shared/angular/*": ["libs/shared/angular/src/lib/*"]
+    }
+  }
+}
+```
+
+Usage:
+
+```typescript
+import { SharedModule } from '@shared/angular';
+import { MyService } from '@shared/angular/services';
+```
+
+## 7. Library Types
+
+### Feature Library
+
+Contains smart components, routes, and business logic.
+
+```typescript
+// libs/museum/feature-objects/src/index.ts
+export * from './lib/objects.module';
+export * from './lib/containers';
+```
+
+### UI Library
+
+Contains presentational (dumb) components only.
+
+```typescript
+// libs/shared/ui/src/index.ts
+export * from './lib/button/button.component';
+export * from './lib/card/card.component';
+```
+
+### Data Access Library
+
+Contains services, state management, and API calls.
+
+```typescript
+// libs/museum/data-access/src/index.ts
+export * from './lib/services/objects.service';
+export * from './lib/+state/objects.facade';
+```
+
+### Utility Library
+
+Contains pure functions, helpers, and utilities.
+
+```typescript
+// libs/shared/util-forms/src/index.ts
+export * from './lib/validators';
+export * from './lib/form-helpers';
+```
+
+## 8. Caching
+
+Nx caches task results. Configure in `nx.json`:
+
+```json
+{
+  "targetDefaults": {
+    "build": {
+      "cache": true,
+      "dependsOn": ["^build"]
+    },
+    "test": {
+      "cache": true
+    },
+    "lint": {
+      "cache": true
+    }
+  }
+}
+```
+
+## 9. Task Dependencies
+
+Define task execution order:
+
+```json
+{
+  "targetDefaults": {
+    "build": {
+      "dependsOn": ["^build"]
+    },
+    "test": {
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+- `^build` means build dependencies first
+- `build` means build this project first
+
+## 10. Generators (Nx 14 / @nrwl)
+
+Create new code with generators:
+
+```bash
+# Generate Angular component
+nx g @nrwl/angular:component my-component --project=shared-angular
+
+# Generate Angular service
+nx g @nrwl/angular:service my-service --project=shared-angular
+
+# Generate library
+nx g @nrwl/angular:library my-lib --directory=shared
+
+# Generate module
+nx g @nrwl/angular:module my-module --project=shared-angular
+
+# Dry run (preview changes)
+nx g @nrwl/angular:component my-component --dry-run
+```
+
+## 11. CI/CD Integration
+
+```yaml
+# Example GitHub Actions
+- name: Install dependencies
+  run: npm ci
+
+- name: Run affected lint
+  run: npx nx affected --target=lint --base=origin/main
+
+- name: Run affected test
+  run: npx nx affected --target=test --base=origin/main
+
+- name: Run affected build
+  run: npx nx affected --target=build --base=origin/main --configuration=production
+```
+
+## 12. Best Practices (Nx 14)
+
+1. **Keep apps thin** - Business logic in libraries
+2. **Use affected** - Only build/test what changed
+3. **Leverage caching** - Let Nx cache task results
+4. **Consistent naming** - Follow naming conventions
+5. **Define boundaries** - Use tags and constraints
+6. **Path aliases** - Use `@scope/lib` imports
+7. **Use @nrwl packages** - NOT @nx packages in Nx 14
+
+## 13. Package Differences
+
+| Feature | @nrwl (Nx 14) | @nx (Modern) |
+|---------|--------------|--------------|
+| Jest | `@nrwl/jest:jest` | `@nx/jest:jest` |
+| Linter | `@nrwl/linter:eslint` | `@nx/eslint:lint` |
+| Angular | `@nrwl/angular:*` | `@nx/angular:*` |
+| Node | `@nrwl/node:*` | `@nx/node:*` |
+| Cypress | `@nrwl/cypress:*` | `@nx/cypress:*` |