Yeoman generator for applications on VA.gov

Requirements

• Node.js 22.0.0+

Installation

The generator is already installed as a devDependency of vets-website.

Local Development Setup

If you're working on this generator itself, you'll need to link it locally to test your changes.

Quick Start (Recommended)

# From generator-vets-website root:
nvm use                      # Use Node version from .nvmrc
npm install                  # Install dependencies
npm run link:vets-website    # Link to vets-website for testing

This creates a symlink so vets-website uses your local development version.

Test Your Changes

# From generator-vets-website root:
npm run generate

This runs the generator in vets-website using a compatible yo CLI version. Any changes to the generator will be automatically reflected due to the npm link.

Why npm run generate instead of yarn new:app?

Generator v4.0.0 uses [email protected] which requires a compatible version of the yo CLI. If vets-website has not yet been updated, its older yo version will cause errors like "Cannot add property resolved, object is not extensible". The npm run generate command uses the compatible yo from this repo's node_modules.

Once vets-website updates its dependencies, you can use yarn new:app directly from vets-website.

Clean Up

# From generator-vets-website root:
npm run unlink:vets-website

Manual Setup (Alternative)

If you prefer to set up the links manually:

1. Create global symlink (from generator-vets-website):

   npm link

2. Link into vets-website (from vets-website):

   npm link @department-of-veterans-affairs/generator-vets-website

3. Clean up when done:

   # From vets-website:
   npm unlink --no-save @department-of-veterans-affairs/generator-vets-website
   # From generator-vets-website:
   npm unlink

Available Scripts

| Script | Description | |--------|-------------| | npm test | Run unit tests (89 tests) | | npm run lint | Run ESLint | | npm run e2e | Run all E2E tests | | npm run e2e:dry-run | Run E2E tests for dry-run modes only | | npm run e2e:real | Run E2E tests with real file generation | | npm run link:vets-website | Link generator to vets-website for local development | | npm run unlink:vets-website | Remove link from vets-website | | npm run generate | Run generator in vets-website (uses compatible yo version) |

E2E Testing

The E2E test suite validates the generator works correctly end-to-end:

# Run all E2E tests (unit tests + dry-run + real generation)
npm run e2e

# Run only dry-run E2E tests (no files created)
npm run e2e:dry-run

# Run real file generation tests (creates files in temp directory)
npm run e2e:real

Note: E2E tests require vets-website to be cloned as a sibling directory (../vets-website).

Usage

The generator supports two modes of operation:

Interactive Mode

# From vets-website directory
yarn run new:app

The generator will guide you through all required information with helpful prompts and validation.

Dry Run Interactive Mode

To preview what files would be generated without actually creating them:

yo @department-of-veterans-affairs/vets-website \
  --dry-run-interactive \
  --appName="My App" \
  --folderName="my-app" \
  --entryName="my-app" \
  --rootUrl="/my-app" \
  --isForm=true

This mode:

• Shows what prompts would have been asked if this were a standard interactive run, what defaults would be used, and what would be missing
• Displays a list of files that would be generated
• Does not create any actual files or modify the filesystem

Non-Interactive Mode

Provide all arguments upfront to skip prompts entirely. Note: CLI mode requires explicit values for most fields since it cannot rely on interactive prompts or defaults:

# From vets-website directory
yo @department-of-veterans-affairs/vets-website \
  --force \
  --appName="My App" \
  --folderName="my-app" \
  --entryName="my-app" \
  --rootUrl="/my-app" \
  --isForm=true \
  --slackGroup="@my-group" \
  --contentLoc="../vagov-content" \
  --formNumber="21P-530" \
  --trackingPrefix="burials-530-" \
  --respondentBurden="30" \
  --ombNumber="2900-0797" \
  --expirationDate="12/31/2026" \
  --benefitDescription="burial benefits" \
  --usesVetsJsonSchema=false \
  --usesMinimalHeader=true \
  --addToMyVaSip=true \
  --templateType="WITH_1_PAGE"

Use --force option to automatically overwrite existing files without prompting.

Dry Run Non-Interactive Mode

To preview what files would be generated without creating them, using predefined arguments. This mode requires all necessary CLI arguments since it cannot prompt for missing values:

yo @department-of-veterans-affairs/vets-website \
  --dry-run-non-interactive \
  --appName="My App" \
  --folderName="my-app" \
  --entryName="my-app" \
  --rootUrl="/my-app" \
  --isForm=true \
  --slackGroup="@my-group" \
  --contentLoc="../vagov-content" \
  --formNumber="21P-530" \
  --trackingPrefix="burials-530-" \
  --respondentBurden="30" \
  --ombNumber="2900-0797" \
  --expirationDate="12/31/2026" \
  --benefitDescription="burial benefits" \
  --usesVetsJsonSchema=false \
  --usesMinimalHeader=true \
  --addToMyVaSip=true \
  --templateType="WITH_1_PAGE"

This mode:

• Requires explicit values for all necessary fields (stricter than interactive mode)
• Shows a detailed list of files that would be generated
• Does not create any actual files or modify the filesystem Use --force option to automatically overwrite existing files without prompting.

Resources

• Guide on using this Yeoman generator with example answers for each prompt
• Basic tutorial for creating and modifying a form application

These resources are also provided by the generator at startup.

Generator Architecture

For specifics on writing a generator, refer to the official Yeoman documentation.

Publishing to npm

When you're ready to publish a new version of the generator to npm:

1. Ensure you're logged in to npm:

   npm login

   You'll need to be added as a maintainer of the @department-of-veterans-affairs/generator-vets-website package.

2. Update the version number:

   npm version patch   # for bug fixes (3.14.1 → 3.14.2)
   npm version minor   # for new features (3.14.1 → 3.15.0)
   npm version major   # for breaking changes (3.14.1 → 4.0.0)

   This will update package.json and create a git tag.

3. Run pre-publish checks:

   npm run prepublishOnly

   This runs npm run prepublishOnly to check for security vulnerabilities.

4. Publish to npm:

   npm publish

Adding New Prompts

If you need to add a new prompt to the generator, follow these steps:

1. Define the Field

Add your new field to the field definitions in lib/prompts.js:

const fieldDefinitions = {
  // ... existing fields
  myNewField: {
    type: 'input',
    message: 'What is your new field value?',
    validate: (input) => {
      if (!input || input.trim() === '') {
        return 'This field is required.';
      }
      return true;
    },
    filter: (input) => input.trim(),
  },
};

2. Add to Field Groups

Include your field in the appropriate field group(s):

const fieldGroups = {
  core: ['appName', 'folderName', 'entryName', 'rootUrl', 'isForm', 'myNewField'],
  form: ['formNumber', 'ombNumber', 'expirationDate', 'myNewField'],
  // ... other groups
};

3. Add CLI Validation (Optional)

If the field should be available as a CLI argument, add validation in lib/cli-validation.js:

function validateMyNewField(value) {
  if (!value) {
    return 'myNewField is required';
  }
  // Add specific validation logic
  return null; // Return null if valid, error string if invalid
}

4. Update Templates

Use the new field in your templates with EJS syntax:

<!-- In any .ejs template file -->
<div>My new field value: <%= myNewField %></div>

5. Add to CLI Arguments (Optional)

If you want the field to be available as a command-line argument, add it to the options in generators/app/index.js:

// This is typically handled automatically by the field definitions,
// but you may need to add custom logic for complex fields

6. Test Your Changes

1. Link the generator locally: npm run link:vets-website
2. Run unit tests: npm test
3. Run E2E tests: npm run e2e
4. Test manually in vets-website: yarn new:app
5. Verify the field appears in prompts and generates correctly in templates

Node.js Version Migration Notes

Current State (Node 22+)

This generator requires Node.js 22.0.0+ and uses:

• yeoman-generator@^7.5.0 (ESM-only, Node 18.17+ required)
• ES Modules throughout the codebase
• All dependencies are compatible with Node 22+

Migration from v3.x (Node 14)

Version 4.0.0 is a major breaking change that requires Node.js 22+ due to:

1. ESM Conversion: All code has been converted from CommonJS to ES Modules
2. Dependency Upgrades: yeoman-generator, chalk, and other packages now require Node 18.17+
3. Consumer Requirements: Users must upgrade to Node 22+ to use this generator

If you need to use the generator with Node 14, please use version 3.x