Ref-004: Nx Generator Scaffolding Standards

Type

Reference Documentation

Purpose

Defines the generator-first development philosophy and catalogs available Nx generators for code scaffolding in the SEA-Forge™ monorepo architecture.

Core Philosophy

Generator-First Principle: Before writing any code, check if an Nx generator exists to scaffold it.

Benefits

Tooling Integration

Primary Interface

1
2
3
4
5
6
7
8
9
10

# Recommended: Just recipe
just ai-scaffold name=<generator>

# Direct invocation
pnpm exec nx g <generator> <name> [options]

# Discovery
pnpm exec nx list                    # All generators
pnpm exec nx list @nx/js             # Plugin-specific
pnpm exec nx g @nx/js:library --help # Generator schema

Automation References

Installed Generator Catalog

@nx/js - TypeScript/JavaScript Libraries

Use Cases: Shared utilities, domain logic, business rules, data models, API clients, type definitions

Command:

1

pnpm exec nx g @nx/js:library <name> --directory=libs/<domain>

Options:

@nx/react - React Components & Libraries

Use Cases: UI components, feature libraries, custom hooks, state management

Commands:

1
2
3
4
5
6
7
8
9
10
11

# Component library
pnpm exec nx g @nx/react:library <name> --directory=libs/ui

# Standalone component
pnpm exec nx g @nx/react:component <Name> --project=<lib>

# Custom hook
pnpm exec nx g @nx/react:hook use<Name> --project=<lib>

# Redux slice
pnpm exec nx g @nx/react:redux <name> --project=<lib>

Options:

@nx/node - Node.js Applications

Use Cases: REST APIs, GraphQL servers, CLI tools, background workers, microservices

Command:

1

pnpm exec nx g @nx/node:application <name> --directory=apps

Options:

@nx/jest - Testing Configuration

Use Cases: Add testing to existing projects (usually auto-configured)

Command:

1

pnpm exec nx g @nx/jest:configuration <project>

@nx/workspace - Workspace Utilities

Use Cases: Monorepo management, project restructuring

Commands:

1
2
3
4
5

# Move project
pnpm exec nx g @nx/workspace:move --projectName=<lib> --destination=libs/<path>

# Convert to monorepo
pnpm exec nx g @nx/workspace:convert-to-monorepo

Available (Optional) Generators

Plugin Install Use Case
@nx/next pnpm add -D @nx/next Next.js SSR/static sites
@nx/remix pnpm add -D @nx/remix Remix web applications
@nx/nest pnpm add -D @nx/nest NestJS enterprise backends
@nx/express pnpm add -D @nx/express Lightweight REST APIs
@nx/expo pnpm add -D @nx/expo React Native mobile apps
@nxlv/python pnpm add -D @nxlv/python Python backends, ML models

Workflow Integration

TDD Integration

Red Phase:

  1. Identify need for new module/component
  2. Use generator to create test scaffold
  3. Customize tests per spec requirements
  4. Run test → verify failure

Green Phase:

Refactor Phase:

Spec-Driven Implementation

  1. Read Spec: Review PRD/SDS/TS
  2. Identify Scope: Determine what needs creation (lib, app, component)
  3. Generate: just ai-scaffold name=<generator>
  4. Implement: Add business logic per spec
  5. Test: Follow TDD workflow
  6. Trace: Update traceability matrix

Best Practices

1. Always Use Generators for New Projects

✅ Ensures consistency and proper configuration
✅ Maintains Nx project graph integrity

2. Use Hierarchical Directory Structure

1
2
3
4
5

# Good: Domain-organized
pnpm exec nx g @nx/js:library user-service --directory=libs/domain/user

# Avoid: Flat structure
pnpm exec nx g @nx/js:library user-service

3. Preview Before Executing

1

pnpm exec nx g @nx/react:component Button --dry-run

4. Customize Post-Generation

5. Follow Generator Conventions

Custom Generators

Local generators may exist in generators/ directory.

Usage:

1
2
3
4
5

# List custom generators
ls -la generators/

# Execute custom generator
pnpm exec nx g ./generators/<name>:<schematic> <target>

Check generators/*/schema.json for available options.

Quick Reference Matrix

Need Generator Command
Shared utilities @nx/js:library just ai-scaffold name=@nx/js:library
React component @nx/react:component pnpm exec nx g @nx/react:component <Name>
React library @nx/react:library just ai-scaffold name=@nx/react:library
Custom hook @nx/react:hook pnpm exec nx g @nx/react:hook use<Name>
Node.js API @nx/node:application pnpm exec nx g @nx/node:application api
Next.js app @nx/next:application pnpm exec nx g @nx/next:application web
Mobile app @nx/expo:application pnpm exec nx g @nx/expo:application mobile
Python API @nxlv/python:application pnpm exec nx g @nxlv/python:application api --type=fastapi

Troubleshooting

“Cannot find generator”

“Missing required parameter”

“Project already exists”

External Resources