---
name: library-scaffolder
description: 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`:

```bash
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`:

```bash
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`:

```typescript
/// <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**
   ```bash
   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:

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

[Brief description]
```

### Step 8: Run Full Validation

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