Nx Migration Generator

Nx 플러그인에 Nx Migration을 추가합니다. Migration을 사용하면 nx migrate가 플러그인의 이전 버전으로 생성된 프로젝트를 자동으로 업데이트할 수 있습니다. 이는 타겟 이름 변경, 제공된 설정 변경 또는 코드 변경이 필요한 종속성 업데이트와 같은 주요 변경 사항이 있을 때 유용합니다.

이 제너레이터는 마이그레이션을 스캐폴딩하고, 플러그인의 migrations.json에 등록하며, 플러그인의 package.json에 nx-migrations 필드를 연결합니다(존재하지 않는 경우 둘 다 생성).

권장 설정

마이그레이션의 기본 프로젝트로 ts#nx-plugin 제너레이터를 사용하는 것을 권장합니다. 이 제너레이터는 제너레이터와 마이그레이션을 게시하도록 설정된 플러그인 프로젝트를 구성합니다.

사용법

Migration 생성

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - ts#nx-migration
5. 필수 매개변수 입력
6. 클릭 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

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

yarn

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

npm

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

bun

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

옵션

매개변수	타입	기본값	설명
project 필수	string	-	마이그레이션을 추가할 Nx Plugin 프로젝트입니다. ts#nx-plugin 생성기를 사용하여 생성하는 것을 권장합니다.
name 필수	string	-	마이그레이션 이름, kebab-case 형식으로 작성 (예: rename-foo-target)
description	string	-	마이그레이션이 수행하는 작업에 대한 설명, nx migrate 명령어로 표시됨
kind	deterministic | agentic | hybrid	deterministic	마이그레이션의 종류: deterministic (코드모드), agentic (사용자 소유 코드에 AI가 적용하는 프롬프트), 또는 hybrid (기계적인 부분을 처리한 후 에이전트에게 넘기는 코드모드)
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요(후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다). 마지막에 한 번만 설치하세요.

세 가지 종류의 마이그레이션

마이그레이션은 세 가지 형태로 제공되며, migrations.json 항목이 가지는 필드에 따라 구분됩니다. --kind를 전달하여 선택하세요(기본값 deterministic):

• Deterministic (implementation) — 정확한 이전/이후가 있는 코드모드입니다. CI 및 비대화형 터미널을 포함하여 무인으로 실행됩니다. 변경 사항이 나타나는 모든 곳에서 안정적으로 일치시킬 수 있는 형태를 가진 경우 단독으로 사용하세요.
• Agentic (prompt) — Nx의 에이전트 기반 nx migrate 흐름을 통해 사용자의 로컬 코딩 에이전트가 적용하는 마크다운 지침 파일입니다. 올바른 편집이 사용자가 구축한 내용에 따라 달라지기 때문에 기계적인 이전/이후가 적용되지 않는 경우 단독으로 사용하세요. 에이전트가 실행되지 않는 경우(CI, 에이전트 미설치, 동의 거부), Nx는 프롬프트를 수동 지침으로 표시합니다. 따라서 프롬프트를 독립적이고 사람이 실행 가능한 단계로 작성하세요.
• Hybrid (implementation + prompt) — 하나의 변경 사항의 두 부분이며, 일반적으로 올바른 선택입니다. 제너레이터가 제공하는 모든 것은 사용자가 소유하고 수정했을 수 있는 코드이므로, 코드모드는 안전하게 일치시킬 수 있는 만큼 수행하고 변경한 내용과 건너뛴 내용을 설명하는 agentContext를 반환합니다. Nx는 해당 컨텍스트를 쌍을 이루는 prompt에 전달하여 에이전트가 나머지 부분에 집중하도록 합니다.

제너레이터 출력

제너레이터는 선택한 kind에 따라 플러그인 프로젝트의 소스 폴더 아래에 다음 파일을 생성합니다:

• 디렉터리src/migrations/latest/<name>/

  • migration.ts 코드모드 구현 (deterministic 및 hybrid)
  • migration.spec.ts 마이그레이션 테스트 (deterministic 및 hybrid)
  • prompt.md 에이전트/사람 지침 (agentic 및 hybrid)
• migrations.json 마이그레이션을 등록하기 위해 생성 또는 업데이트됨
• package.json “nx-migrations” 항목을 추가하기 위해 생성 또는 업데이트됨

새 마이그레이션은 latest/에 생성됩니다. 마이그레이션을 출시하는 릴리스별로 그룹화하면 컬렉션이 증가함에 따라 순서를 한눈에 볼 수 있습니다 — 버전을 할당할 때 마이그레이션을 v<x.y.z>/ 폴더로 이동하고(그리고 migrations.json에서 경로를 업데이트) 하세요.

이는 해당 종류에 대한 필드와 version 없이 migrations.json에 마이그레이션을 등록합니다 — 아래 버전 관리를 참조하세요.

Migration 구현

결정론적(또는 하이브리드) 마이그레이션은 가상 파일시스템(Tree)을 변경하고 MigrationReturnObject를 반환하는 함수입니다:

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 — nx migrate 실행 후 사용자에게 표시되는 워크스페이스 전체 메모입니다. 건너뛴 파일(아래 가드레일 참조) 또는 마이그레이션이 수행할 수 없는 수동 후속 조치를 보고하는 데 사용하세요.
• agentContext (hybrid만 해당) — 코드모드가 변경한 내용의 요약으로, Nx의 에이전트 기반 흐름에서 실행될 때 쌍을 이루는 prompt에 전달되어 에이전트가 사용자 소유 부분에 집중할 수 있도록 합니다.

마이그레이션에서 수행할 수 있는 몇 가지 예제 작업(파일 생성, GritQL을 사용한 기존 파일 수정, JSON 읽기 및 업데이트)에 대해서는 Nx Generator 가이드를 참조하세요.

가드레일

마이그레이션은 제어할 수 없는 워크스페이스에 대해 실행되므로 다음을 준수하는 것이 권장됩니다(스캐폴딩된 스켈레톤에 이러한 내용이 포함되어 있습니다):

• 쓰기 전에 패턴 매칭. 대상 파일이 제너레이터가 생성하는 형태에서 벗어난 경우, 사용자의 변경 사항을 덮어쓰는 대신 건너뛰고 nextSteps를 통해 보고하세요.
• 멱등성. 마이그레이션을 다시 실행하면 아무 작업도 수행하지 않아야 합니다.
• 작성한 내용을 포맷하세요. formatFilesInSubtree(tree)로 마무리하여 마이그레이션이 작성한 파일이 올바르게 포맷되도록 하세요.

Migration 테스트

스캐폴딩된 migration.spec.ts는 createTreeUsingTsSolutionSetup()을 사용하여 프리셋이 생성하는 형태와 일치하는 가상 워크스페이스를 구축합니다. 마이그레이션이 워크스페이스를 “이전” 상태에서 대상 상태로 가져오고, 사용자 정의된 파일을 건너뛰고(보고하고), 멱등성이 있는지 테스트하세요:

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');
  });
});

버전 관리

Nx는 사용자가 설치한 플러그인 버전이 마이그레이션의 version보다 낮을 때 마이그레이션을 실행합니다. 이 제너레이터는 version 필드를 작성하지 않습니다 — 마이그레이션을 제공하는 릴리스를 출시할 때 할당하거나(또는 릴리스 프로세스에서 스탬프) 이전 버전에서 업그레이드하는 모든 사용자에게 실행되도록 하세요.

버전을 할당하면 각 종류의 마이그레이션을 하나씩 등록하는 migrations.json은 다음과 같습니다:

{
  "$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"
    }
  }
}

Migration 실행

사용자는 2단계 nx migrate 흐름으로 플러그인의 마이그레이션을 적용합니다 — 보류 중인 마이그레이션을 생성하고, 설치한 다음, 실행합니다:

pnpm

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

yarn

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

npm

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

bun

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

에이전트 기반 및 하이브리드 마이그레이션은 사용 가능한 경우 nx migrate --run-migrations 중에 사용자의 로컬 코딩 에이전트에 의해 적용됩니다.

업그레이드하는 사용자의 관점에서 전체 흐름(결정론적 및 에이전트 기반 마이그레이션의 예제 출력 포함)은 워크스페이스 업그레이드를 참조하세요.