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

用于 VA.gov 应用的 Yeoman 生成器

所需资源

• 节点.js 22.0.0+

安装

发电机已经安装为 devDependency 联 合 国 vets-website。 。 。 .

本地开发设置

如果你正在研究这台发电机, 你需要将它连接到本地测试你的改变.

快速启动( 建议)

# 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

这创造了一个共通点 所以兽医网站 使用您的本地开发版本.

测试您的更改

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

使用相容软件在兽医网站运行生成器 yo CLI版本. 由于 npm 链接,任何对生成器的更改都会被自动反映.

为什么 npm run generate 改为 yarn new:app? 吗?

发电机 v4.0.0 用途 [email protected] 它需要一个兼容的版本 yo CLI(英语:CLI). 如果兽医网站尚未更新,则旧网站 yo 版本会出"无法添加属性已解决,对象无法扩展"等错误. 这个 npm run generate 命令使用相容性 yo 从这个repo的节点 模块.

一旦兽医网站更新它的依赖性,你可以使用 yarn new:app 直接从兽医网站.

清理

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

手动设置( 替代)

如果您喜欢手动设置链接 :

1. 创建全局符号链接 (来自发电机网站):

   npm link
   

2. 连接到兽医网站 (来自兽医网站):

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

3. 完成后清理数字 :

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

可用的脚本

E2E 测试

E2E测试套件验证生成器工作正确端到端:

# 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

说明: E2E测试需要 vets-website 被复制为兄弟姐妹目录( e)../vets-website) (中文(简体) ).

使用量

生成器支持两种操作模式:

交互式模式

# From vets-website directory
yarn run new:app

生成器会用有用的提示和验证来引导您获取所有所需的信息 .

干运行互动模式

要预览将生成哪些文件而不实际创建它们 :

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

此模式 :

• 显示如果这是标准交互运行会询问的提示, 使用什么默认, 以及缺少什么
• 显示将要生成的文件列表
• 不创建任何实际文件或修改文件系统

非交互模式

提前提供所有参数以全部跳过提示 . 说明: CLI 模式要求大多数字段有明确的值,因为它不能依赖交互式提示或默认:

# 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"

使用 --force 选项可以自动覆盖已有文件而不提示.

干运行非交互模式

使用预定义的参数预览将生成哪些文件而不创建它们 . 此模式需要所有必要的 CLI 参数 因为它不能提示缺失的值 :

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"

此模式 :

• 需要所有必要的字段的清晰值( 限定于交互模式)
• 显示将要生成的文件的详细列表
• 不创建任何实际文件或修改文件系统 使用 --force 选项可以自动覆盖已有文件而不提示.

资源

• 使用 Yeoman 生成器的指南, 以每个提示的答案为例
• 创建和修改窗体应用程序的基本教程

这些资源也由启动时的发电机提供.

发电机建筑

关于写发电机的细节, 参考官方的约曼文档。 。 。 .

发布到 npm

当您准备好发布新版本的生成器到 npm:

1. 确保您登录到 npm :

   npm login
   

   您需要加入为维护者 @department-of-veterans-affairs/generator-vets-website 软件包.

2. 更新版本编号 :

   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)
   

   这将更新 package.json 并创建 git 标签 .

3. 运行打印前检查 :

   npm run prepublishOnly
   

   这个运行 npm run prepublishOnly 检查安全弱点.

4. 发布到 npm :

   npm publish
   

添加新提示

如果您需要给生成器添加新的提示, 请遵循这些步骤 :

1. 界定领域

在 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. 添加到外地小组

将您的字段纳入相应的字段组:

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

3. 增加CLI验证(可选)

如果该字段可作为 CLI 参数,请在 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. 更新模板

使用 EJS 语法模板中的新字段 :

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

5. 加入CLI参数(备选)

如果您想要将字段用作命令行参数,请添加到其中的选项中 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. 测试您的更改

1. 连接本地生成器 : npm run link:vets-website
2. 运行单元测试 : npm test
3. 运行 E2E 测试 : npm run e2e
4. 在兽医网站进行人工测试: yarn new:app
5. 校验字段在提示中出现并在模板中正确生成

节点.js 版本迁移说明

当前状态(22号+)

该生成器需要22.0.0+节点,并使用:

• yeoman-generator@^7.5.0 (仅ESM型,节点18.17+需要)
• 整个编码库的ES模块
• 所有依赖关系都与22+节点兼容

从 v3.x (节点 14) 迁移

4.0.0版本是一次重大的突破性改变,由于:

1. EME 转换: 所有代码已经从普通JS转换为ES模块
2. 依赖性升级: yoman-generator, 粉笔等软件包现在需要18.17+节点
3. 消费者要求: 用户必须升级到22+节点才能使用此生成器

如果您需要使用带有节点14的生成器, 请使用版本 3. x