Nx Migration Generator

Thêm một Nx Migration vào một Nx Plugin. Migrations cho phép nx migrate tự động cập nhật các dự án được tạo bởi phiên bản trước của plugin của bạn khi bạn thực hiện thay đổi phá vỡ — đổi tên targets, thay đổi cấu hình được cung cấp, hoặc nâng cấp dependency yêu cầu các thay đổi code đi kèm.

Generator này tạo khung migration, đăng ký nó trong migrations.json của plugin của bạn, và kết nối trường nx-migrations vào package.json của plugin của bạn (tạo cả hai nếu chúng chưa tồn tại).

Cách Sử Dụng

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - ts#nx-migration
Điền các tham số bắt buộc
Nhấp Generate

pnpm nx g @aws/nx-plugin:ts#nx-migration

yarn nx g @aws/nx-plugin:ts#nx-migration

npx nx g @aws/nx-plugin:ts#nx-migration

bunx nx g @aws/nx-plugin:ts#nx-migration

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm nx g @aws/nx-plugin:ts#nx-migration --dry-run

yarn nx g @aws/nx-plugin:ts#nx-migration --dry-run

npx nx g @aws/nx-plugin:ts#nx-migration --dry-run

bunx nx g @aws/nx-plugin:ts#nx-migration --dry-run

Tùy Chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án Nx Plugin để thêm migration vào. Chúng tôi khuyến nghị sử dụng generator ts#nx-plugin để tạo dự án này.
name Bắt buộc	string	-	Tên migration, theo định dạng kebab-case (ví dụ: rename-foo-target)
description	string	-	Mô tả về những gì migration thực hiện, được hiển thị bởi nx migrate
kind	deterministic \| agentic \| hybrid	deterministic	Loại migration: deterministic (một codemod), agentic (một prompt được áp dụng bởi AI cho code do người dùng sở hữu), hoặc hybrid (một codemod thực hiện phần cơ học rồi chuyển giao cho agent)
preferInstallDependencies	boolean	true	Có nên ưu tiên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi thực hiện hàng loạt nhiều generator (việc cài đặt vẫn chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Ba loại migration

Migrations có ba dạng, được phân biệt bởi các trường mà mục nhập migrations.json mang theo. Truyền --kind để chọn (mặc định deterministic):

Deterministic (implementation) — một codemod với trước/sau chính xác. Chạy tự động, bao gồm trong CI và các terminal không tương tác. Sử dụng nó một mình khi thay đổi có một hình dạng mà bạn có thể khớp một cách đáng tin cậy ở mọi nơi nó xuất hiện.
Agentic (prompt) — một tệp hướng dẫn markdown được áp dụng bởi coding agent cục bộ của người dùng thông qua luồng nx migrate agentic của Nx. Sử dụng nó một mình khi không có trước/sau cơ học nào phù hợp, bởi vì việc chỉnh sửa đúng phụ thuộc vào những gì người dùng đã xây dựng. Khi không có agent chạy (CI, không cài đặt agent, từ chối đồng ý), Nx hiển thị prompt dưới dạng hướng dẫn thủ công — vì vậy hãy viết prompts dưới dạng các bước độc lập, có thể thực hiện bởi con người.
Hybrid (implementation + prompt) — cả hai nửa của một thay đổi, và thường là lựa chọn đúng đắn. Mọi thứ mà generators của bạn cung cấp là code mà người dùng sở hữu và có thể đã sửa đổi, vì vậy codemod thực hiện nhiều nhất có thể khớp một cách an toàn và trả về agentContext mô tả những gì nó đã thay đổi và những gì nó đã bỏ qua; Nx truyền context đó cho prompt được ghép đôi, điều hướng agent đến phần còn lại.

Đầu Ra Của Generator

Generator tạo các tệp sau trong thư mục nguồn của dự án plugin của bạn, tùy thuộc vào kind được chọn:

Thư mụcsrc/migrations/latest/<name>/
- migration.ts Triển khai codemod (deterministic và hybrid)
- migration.spec.ts Tests cho migration của bạn (deterministic và hybrid)
- prompt.md Hướng dẫn cho agent/con người (agentic và hybrid)
migrations.json Được tạo hoặc cập nhật để đăng ký migration của bạn
package.json Được tạo hoặc cập nhật để thêm mục “nx-migrations”

Một migration mới được đặt trong latest/. Nhóm các migrations theo bản phát hành mà gửi chúng giúp thứ tự của chúng hiển thị rõ ràng khi bộ sưu tập phát triển — di chuyển một migration vào thư mục v<x.y.z>/ (và cập nhật các đường dẫn của nó trong migrations.json) khi bạn gán phiên bản của nó.

Nó đăng ký migration trong migrations.json với các trường cho loại của nó và không có version — xem Versioning bên dưới. Khóa đã đăng ký được thêm tiền tố với thư mục mà migration nằm trong đó (latest-<name>), vì vậy việc tái sử dụng một tên cho một thay đổi sau này không thể ghi đè âm thầm một migration đã được gửi đi.

Triển Khai một Migration

Một migration deterministic (hoặc hybrid) là một hàm biến đổi hệ thống tệp ảo (Tree), trả về một MigrationReturnObject. Đây là một migration hybrid, trả về cả hai:

import { type MigrationReturnObject, type Tree } from '@nx/devkit';
import { formatFilesInSubtree } from '@aws/nx-plugin/sdk/utils/format';

export default async function migration(
  tree: Tree,
): Promise<MigrationReturnObject> {
  const nextSteps: string[] = [];
  const agentContext: string[] = [];

  // Read and update the files your generators produce here.

  await formatFilesInSubtree(tree);

  return { nextSteps, agentContext };
}

nextSteps — các ghi chú trên toàn workspace được hiển thị cho người dùng sau khi nx migrate chạy. Sử dụng chúng để báo cáo các tệp bạn đã bỏ qua (xem các guardrails bên dưới) hoặc các bước tiếp theo thủ công mà migration không thể thực hiện.
agentContext (chỉ hybrid) — một tóm tắt về những gì codemod đã thay đổi, được truyền cho prompt được ghép đôi khi nó chạy dưới luồng agentic của Nx để agent có thể tập trung vào các phần thuộc sở hữu của người dùng.

Để biết một số ví dụ về các thao tác bạn có thể thực hiện trong migration của mình (tạo tệp, sửa đổi các tệp hiện có bằng GritQL, đọc và cập nhật JSON), hãy tham khảo hướng dẫn Nx Generator.

Guardrails

Migrations chạy trên các workspace mà bạn không kiểm soát, vì vậy được khuyến nghị tuân thủ các quy tắc sau (khung được tạo sẵn đã tích hợp chúng):

Pattern-match trước khi ghi. Nếu một tệp đích đã khác biệt so với hình dạng mà generators của bạn tạo ra, hãy bỏ qua nó và báo cáo nó qua nextSteps, hoặc xem xét một migration hybrid, thay vì ghi đè các thay đổi của người dùng.
Idempotent. Chạy lại migration phải là một no-op.
Định dạng những gì bạn ghi. Kết thúc với formatFilesInSubtree(tree) để các tệp mà migration của bạn ghi được định dạng chính xác.

Kiểm Thử Migration Của Bạn

migration.spec.ts được tạo sẵn sử dụng createTreeUsingTsSolutionSetup() để xây dựng một workspace ảo khớp với hình dạng mà preset của chúng tôi tạo ra. Kiểm tra rằng migration đưa một workspace từ trạng thái “trước” đến trạng thái đích, bỏ qua (và báo cáo) code mà nó không nhận ra, và là idempotent:

import type { Tree } from '@nx/devkit';
import { createTreeUsingTsSolutionSetup } from '@aws/nx-plugin/sdk/utils/test';
import migration from './migration';

describe('my migration', () => {
  let tree: Tree;

  beforeEach(() => {
    tree = createTreeUsingTsSolutionSetup();
  });

  it('should update the generated shape', async () => {
    // Set up a tree with the "before" state
    tree.write('project.json', JSON.stringify({ targets: { foo: {} } }));

    // Run the migration
    await migration(tree);

    // Check that the tree matches the target state
    const projectJson = JSON.parse(tree.read('project.json', 'utf-8'));
    expect(projectJson.targets).toHaveProperty('bar');
    expect(projectJson.targets).not.toHaveProperty('foo');
  });
});

Unit tests chỉ chứng minh migration thực hiện những gì bạn đã viết nó để làm. Cũng kiểm tra nó với một workspace được tạo bởi phiên bản đã xuất bản của plugin của bạn — trạng thái mà người dùng của bạn nâng cấp từ đó — và xác nhận kết quả khớp với những gì generators của bạn tạo ra ngày hôm nay: kiểm tra diff, tạo các dự án tương tự vào một workspace mới và so sánh, kiểm tra workspace vẫn build được, sau đó chạy lại migration để xác nhận nó không thay đổi gì. Lặp lại với một workspace mà bạn đã tùy chỉnh trước, để kiểm tra migration để các chỉnh sửa của bạn nguyên vẹn và báo cáo chúng thay thế.

Versioning

Nx chạy một migration khi phiên bản plugin đã cài đặt của người dùng nhỏ hơn version của migration. Generator này ghi không có trường version — gán nó (hoặc đóng dấu nó từ quy trình phát hành của bạn) khi bạn cắt bản phát hành mà gửi migration, để nó chạy cho mọi người nâng cấp từ phiên bản trước đó.

Sau khi bạn gán các phiên bản, một migrations.json đăng ký một migration của mỗi loại trông như thế này:

{
  "$schema": "http://json-schema.org/schema",
  "name": "my-plugin",
  "generators": {
    "v2.0.0-rename-foo-target": {
      "version": "2.0.0",
      "description": "Rename the foo target to bar",
      "implementation": "./src/migrations/v2.0.0/rename-foo-target/migration"
    },
    "v3.0.0-migrate-custom-handlers": {
      "version": "3.0.0",
      "description": "Update custom handlers for the new API",
      "prompt": "./src/migrations/v3.0.0/migrate-custom-handlers/prompt.md"
    },
    "v4.0.0-upgrade-framework": {
      "version": "4.0.0",
      "description": "Upgrade the framework and reconcile call sites",
      "implementation": "./src/migrations/v4.0.0/upgrade-framework/migration",
      "prompt": "./src/migrations/v4.0.0/upgrade-framework/prompt.md"
    }
  }
}

Chạy Migrations

Người dùng áp dụng các migrations của plugin của bạn với luồng hai bước nx migrate — tạo các migrations đang chờ, cài đặt, sau đó chạy chúng:

pnpm nx migrate my-plugin@latest
pnpm nx migrate --run-migrations

yarn nx migrate my-plugin@latest
yarn nx migrate --run-migrations

npx nx migrate my-plugin@latest
npx nx migrate --run-migrations

bunx nx migrate my-plugin@latest
bunx nx migrate --run-migrations

Các migrations agentic và hybrid được áp dụng bởi coding agent cục bộ của người dùng trong quá trình nx migrate --run-migrations khi có sẵn.

Để biết luồng đầy đủ từ góc độ người dùng đang nâng cấp — bao gồm đầu ra ví dụ cho các migrations deterministic và agentic — xem Nâng Cấp Workspace Của Bạn.