ISA-Frontend/.claude/skills/library-scaffolder/SKILL.md

name, description

name	description
library-scaffolder	This skill should be used when creating new Angular libraries in the ISA-Frontend monorepo. It handles Nx library generation with proper naming conventions, Vitest configuration with JUnit/Cobertura reporters, path alias setup, and validation. Use this skill when the user wants to create a new library, scaffold a feature/data-access/ui/util library, or requests "new library" creation.

Library Scaffolder

Overview

Automate the creation of new Angular libraries following ISA-Frontend conventions. This skill handles the complete scaffolding workflow including Nx generation, Vitest configuration with CI/CD integration, path alias verification, and initial validation.

When to Use This Skill

Invoke this skill when:

• User requests creating a new library
• User mentions "new library", "scaffold library", or "create feature"
• User wants to add a new domain/layer/feature to the monorepo

Required Parameters

User must provide:

• domain: Domain name (oms, remission, checkout, ui, core, shared, utils)
• layer: Layer type (feature, data-access, ui, util)
• name: Library name in kebab-case

Scaffolding Workflow

Step 1: Validate Input

1. Verify Domain

   • Use docs-researcher to check docs/library-reference.md
   • Ensure domain follows existing patterns

2. Validate Layer

   • Must be one of: feature, data-access, ui, util

3. Check Name

   • Must be kebab-case
   • Must not conflict with existing libraries

4. Determine Path Depth

   • 3 levels: libs/domain/layer/name → ../../../
   • 4 levels: libs/domain/type/layer/name → ../../../../

Step 2: Run Dry-Run

Execute Nx generator with --dry-run:

npx nx generate @nx/angular:library \
  --name=[domain]-[layer]-[name] \
  --directory=libs/[domain]/[layer]/[name] \
  --importPath=@isa/[domain]/[layer]/[name] \
  --style=css \
  --unitTestRunner=vitest \
  --standalone=true \
  --skipTests=false \
  --dry-run

Review output with user before proceeding.

Step 3: Generate Library

Execute without --dry-run:

npx nx generate @nx/angular:library \
  --name=[domain]-[layer]-[name] \
  --directory=libs/[domain]/[layer]/[name] \
  --importPath=@isa/[domain]/[layer]/[name] \
  --style=css \
  --unitTestRunner=vitest \
  --standalone=true \
  --skipTests=false

Step 4: Configure Vitest with JUnit and Cobertura

Update libs/[path]/vite.config.mts:

/// <reference types='vitest' />
import { defineConfig } from 'vite';
import angular from '@analogjs/vite-plugin-angular';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';

export default
// @ts-expect-error - Vitest reporter tuple types have complex inference issues
defineConfig(() => ({
  root: __dirname,
  cacheDir: '../../../node_modules/.vite/libs/[path]',
  plugins: [angular(), nxViteTsPaths(), nxCopyAssetsPlugin(['*.md'])],
  test: {
    watch: false,
    globals: true,
    environment: 'jsdom',
    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
    setupFiles: ['src/test-setup.ts'],
    reporters: [
      'default',
      ['junit', { outputFile: '../../../testresults/junit-[library-name].xml' }],
    ],
    coverage: {
      reportsDirectory: '../../../coverage/libs/[path]',
      provider: 'v8' as const,
      reporter: ['text', 'cobertura'],
    },
  },
}));

Critical: Adjust path depth based on library location.

Step 5: Verify Configuration

1. Check Path Alias

   • Verify tsconfig.base.json was updated
   • Should have: "@isa/[domain]/[layer]/[name]": ["libs/[domain]/[layer]/[name]/src/index.ts"]

2. Run Initial Test

   npx nx test [library-name] --coverage.enabled=true --skip-nx-cache
   

3. Verify CI/CD Files Created

   • JUnit XML: testresults/junit-[library-name].xml
   • Cobertura XML: coverage/libs/[path]/cobertura-coverage.xml

Step 6: Create Library README

Use docs-researcher to find similar library READMEs, then create comprehensive documentation including:

• Overview and purpose
• Installation/import instructions
• API documentation
• Usage examples
• Testing information (Vitest + Angular Testing Utilities)

Step 7: Update Library Reference

Add entry to docs/library-reference.md under appropriate domain:

#### `@isa/[domain]/[layer]/[name]`
**Path:** `libs/[domain]/[layer]/[name]`
**Type:** [Feature/Data Access/UI/Util]
**Testing:** Vitest

[Brief description]

Step 8: Run Full Validation

# Lint
npx nx lint [library-name]

# Test with coverage
npx nx test [library-name] --coverage.enabled=true --skip-nx-cache

# Build (if buildable)
npx nx build [library-name]

# Dependency graph
npx nx graph --focus=[library-name]

Step 9: Generate Creation Report

Library Created Successfully
============================

Library Name: [domain]-[layer]-[name]
Path: libs/[domain]/[layer]/[name]
Import Alias: @isa/[domain]/[layer]/[name]

✅ Configuration
----------------
Test Framework: Vitest with Angular Testing Utilities
Style: CSS
Standalone: Yes
JUnit Reporter: ✅ testresults/junit-[library-name].xml
Cobertura Coverage: ✅ coverage/libs/[path]/cobertura-coverage.xml

📦 Import Statement
-------------------
import { Component } from '@isa/[domain]/[layer]/[name]';

🧪 Test Commands
----------------
npx nx test [library-name] --skip-nx-cache
npx nx test [library-name] --coverage.enabled=true --skip-nx-cache

📝 Next Steps
-------------
1. Develop library features
2. Write tests using Vitest + Angular Testing Utilities
3. Add E2E attributes (data-what, data-which) to templates
4. Update README with usage examples

Error Handling

Issue: Path depth mismatch

• Count directory levels from workspace root
• Adjust ../ in outputFile and reportsDirectory

Issue: TypeScript errors in vite.config.mts

• Add // @ts-expect-error before defineConfig()

Issue: Path alias not working

• Check tsconfig.base.json
• Run npx nx reset
• Restart TypeScript server

References

• docs/guidelines/testing.md (Vitest, JUnit, Cobertura sections)
• docs/library-reference.md (domain patterns)
• CLAUDE.md (Library Organization, Testing Framework sections)
• Nx Angular Library Generator: https://nx.dev/nx-api/angular/generators/library