AI 기반 SPFx 1.22 업그레이드: 재현 가능한 프로세스 흐름
Source: Dev.to
Source: …
소개
SharePoint Framework (SPFx) 1.22가 출시되면서 Microsoft는 완전히 새로운 빌드 체인을 도입했습니다. 변경 사항이 너무 방대해서 SPFx 1.22는 마이너 업데이트라기보다 2.0 릴리스에 가깝게 느껴집니다.
기존의 gulp/webpack 툴체인은 Microsoft의 새로운 빌드 시스템인 Heft로 대체되고 있습니다:
핵심 질문은 다음과 같습니다: 기존 SPFx 프로젝트를 SPFx 1.22와 Heft로 업그레이드하면서, 특히 오래된 프로젝트를 처음 다룰 때 아무것도 깨지지 않게 하려면 어떻게 해야 할까요?
TL;DR
이 글에서는 SPFx 프로젝트를 SPFx 1.22와 Heft 빌드 체인으로 업그레이드하는 재현 가능한 AI 기반 프로세스를 단계별로 안내합니다. 마지막에는 어떤 프로젝트에도 바로 적용할 수 있는 AI 프롬프트를 제공하니 그대로 복사해 사용하면 됩니다.
DISCLAIMER – spfx‑fast‑serve를 사용하는 경우 흐름이 다를 수 있으며, 본 가이드는 일반 SPFx 프로젝트를 기준으로 작성되었습니다.
SPFx 업그레이드에 대한 이전 방법
작성 시점에 지원되는 유일한 버전은 **1.22.0 (release candidate 0)**였습니다. 코드를 정식 버전으로 업데이트해야 합니다.
Copilot을 사용하기 시작한 이후로, 업그레이드 출력을 바로 Copilot에 입력하면 Copilot이 업그레이드를 수행해 줍니다.
Source: …
하나의 프롬프트로 업그레이드
수동 업그레이드가 자동으로 더 좋다는 뜻은 아닙니다. 사람은 실수를 하고 중요한 세부 사항을 간과할 수 있습니다. 인공지능도 오류를 범하지만, 스스로 문제를 감지하고 수정할 수 있는 경우가 많습니다(다소 무섭게 들릴 수도 있죠).
업그레이드를 처리하기 위해 저는 하나의 프롬프트를 만들고 여러 SPFx 프로젝트에 걸쳐 테스트했습니다. 여기에는 동일한 저장소에 여러 프로젝트가 공존하는 시나리오도 포함됩니다.
이제 자세히 살펴보겠습니다.
1. 지침 읽기
업그레이드 정의는 여기 있습니다:
Follow these instructions to upgrade to the latest SPFx version using Heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchainAI에게 이 지침을 제공함으로써 제가 정확히 무엇을 하고 싶은지 알려줍니다. 저는 업그레이드 정의를 읽고, 분석하며, 필요한 단계에 대한 기본적인 이해를 얻습니다.
2. 안전망 구축
AI를 사용할 때 업그레이드 후 마주하게 될 모든 위험을 알고 싶습니다. 저장소에는 제가 알지 못하는 숨겨진 문서가 종종 포함되어 있기 때문입니다.
Before you start the migration, perform a risk assessment of the
current solution and document it in a Markdown file.두 번째 단계에서는 프로젝트에 대한 전체 분석을 제공하고, 잠재적인 문제점을 강조하며, 손상이 발생하기 전에 업그레이드를 중단할 수 있게 해줍니다.
예시 위험‑평가 출력
먼저 현재 솔루션의 인벤토리를 생성하고, 이어서 식별된 위험을 나열합니다.
이를 통해 위험을 어떻게 다룰지 명확히 파악할 수 있습니다.
3. 위험을 수락한 후 진행
위험을 검토하고 수락하면 AI가 실제 마이그레이션을 진행합니다.
Once those risks have been accepted, based on the current branch,
please create a new upgrade branch, follow the instructions, using
only the referenced versions, including optional steps that match my solution,
and normalize all npm scripts to follow best‑practice colon notation.- 새 브랜치 생성 – 메인 브랜치를 보호합니다; 업그레이드가 실패하면 업그레이드 브랜치를 간단히 삭제하면 됩니다.
- 공식 지침을 단계별로 따르기 – AI가 해당 솔루션에 필요한 선택적 단계들을 판단합니다.
- npm 스크립트 정규화 – 다음 섹션에서 자세히 설명합니다.
4. 모범 사례 따르기 – npm 스크립트 정규화
문서에서는 npm 스크립트에 대한 특정 명명 규칙을 권장합니다. 관련 발췌는 다음과 같습니다:
{
"scripts": {
"test-only": "heft run --only test --",
"deploy": "heft dev-deploy",
"start": "heft start --clean",
"build-watch": "heft build --lite",
"package-solution": "heft package"
}
}프롬프트 라인
... normalize all npm scripts to follow best‑practice colon notation.은 AI에게 하이픈(-)을 사용한 스크립트(예: test-only)를 콜론(:) 기반 형식(예: test:only)으로 바꾸도록 지시합니다. 이렇게 하면 스크립트를 읽고 그룹화하며 실행하기가 더 쉬워집니다(예: npm run test:only).
전체 AI 프롬프트
아래 블록을 복사하여 Copilot/ChatGPT 세션에 붙여넣으면 모든 SPFx 프로젝트에 대해 동일한 업그레이드 흐름을 실행할 수 있습니다:
You are an expert SharePoint Framework developer. Follow these steps to upgrade a project to SPFx 1.22 using Heft:
1. Read the official migration guide:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain
2. Perform a risk assessment of the current solution and write a detailed Markdown report that includes:
- An inventory of the project’s dependencies, custom scripts, and configuration files.
- Potential breaking changes (e.g., deprecated APIs, gulp tasks, custom webpack configs).
- Any hidden documentation or scripts that could affect the upgrade.
3. Present the risk report to the user. Wait for the user to confirm that the risks are accepted.
4. Once accepted:
- Create a new Git branch named `upgrade/spfx-1.22`.
- Follow the migration guide step‑by‑step, using only the versions referenced in the guide.
- For each optional step, decide whether it applies to the current project (based on the risk report) and include it if needed.
- After the migration, update the `package.json` scripts:
* Convert hyphenated script names to colon notation (e.g., `test-only` → `test:only`).
* Ensure the scripts match the examples in the guide:
- `"test:only": "heft run --only test --"`
- `"deploy": "heft dev-deploy"`
- `"start": "heft start --clean"`
- `"build:watch": "heft build --lite"`
- `"package:solution": "heft package"`
5. Run `npm install` and then `heft build` to verify the project builds successfully.
6. If any step fails, revert the changes on the upgrade branch, document the failure in the Markdown report, and stop.
Provide the final upgraded project structure, the updated `package.json`, and a short summary of what changed.결론
명확한 단계별 마이그레이션 가이드와 AI 기반 위험 평가 및 스크립트 정규화를 결합하면 SPFx 프로젝트를 1.22와 Heft로 안전하고 재현 가능하게 업그레이드할 수 있습니다. 위의 단일 프롬프트는 전체 워크플로를 포괄하여 어떤 리포지토리에도 동일한 프로세스를 쉽게 적용할 수 있게 합니다. 업그레이드 즐겁게!
스크립트 명명 규칙
{
"scripts": {
"package-solution": "heft package-solution",
"deploy-azure-storage": "heft deploy-azure-storage",
"eject-webpack": "heft eject-webpack",
"trust-dev-cert": "heft trust-dev-cert",
"untrust-dev-cert": "heft untrust-dev-cert"
}
}스크립트 이름에 하이픈(-)을 사용할 수는 있지만, 흔하지 않은 패턴이라 목록이 늘어날수록 읽기 어려워질 수 있습니다. 보다 일반적이고(그리고 종종 최선‑실천) 권장되는 방법은 콜론 표기법을 사용하는 것으로, 유사한 명령을 그룹화합니다.
{
"scripts": {
"build": "heft build --clean",
"build:watch": "heft build --lite",
"build:prod": "heft build --production",
"devcert:trust": "heft trust-dev-cert",
"devcert:untrust": "heft untrust-dev-cert",
"start": "npm run build:watch",
"test": "heft test",
"test:only": "heft run --only test --"
// ...
}
}이와 같이 변환하면 관련 작업을 그룹화하기가 쉬워집니다(예: 모든 테스트 명령). 또한 특수 린터(stylelint)와 같은 사용자 정의 명령이나 DevOps 작업을 추가할 수도 있습니다. 전반적으로 스크립트가 build, devcert, test, deploy 등과 같은 그룹으로 보다 체계적으로 정리됩니다.
업그레이드 중 수동 변경 사항
업그레이드 후 스크립트를 재구성하기 위해 몇 가지 수동 조정이 필요합니다.
수용 테스트 수행
업그레이드를 수락하기 전에 최종 수용 테스트를 실행하여 모든 것이 정상적으로 작동하는지 확인합니다. 여러 가지 문제가 발생할 수 있습니다: 문서가 불완전하거나, 업그레이드 후 숨겨진 이슈 등이 있습니다.
As a final acceptance run, execute the build command to check for issues.
If issues are found, provide fact‑based solutions.모든 것이 성공하면 축하합니다—업그레이드된 솔루션을 갖게 됩니다. 그렇지 않다면 반복해서 문제를 해결하십시오. “사실에 기반한” 접근을 강조하면 AI가 근거 없는 변경을 하는 것을 방지하고 증거 기반 수정을 장려합니다.
문서화
마지막 단계는 수행한 모든 작업에 대한 적절한 문서를 만드는 것입니다. 이는 참고 자료가 되며, 예상대로 작동하지 않을 경우 발생할 수 있는 놀라움을 없애줍니다.
Provide a detailed summary of the applied configuration changes.
In addition to the summary, recommend updates to the documentation
based on issues encountered during the upgrade.
Also, make a recommendation for the Microsoft upgrade guide.이 단계는 무엇이 잘못되었는지(있는 경우)와 무엇이 수정되었는지를 명확히 제시하기 때문에 매우 중요합니다. Microsoft 문서에서 사소한 문제만 발견한 경우에만 선택 사항입니다.
프롬프트
아래는 SharePoint Framework (SPFx) 솔루션을 SPFx 1.22 로 업그레이드하기 위한 전체 프롬프트입니다. 도구나 마법 없이 필요한 업데이트를 설명하는 명확한 절차만을 제공합니다.
Follow these instructions to upgrade to the latest SPFx version using heft:
https://learn.microsoft.com/en-us/sharepoint/dev/spfx/toolchain/migrate-gulptoolchain-hefttoolchain
Before you start the migration, perform a risk assessment of the current solution and document it in a Markdown file.
Once those risks have been accepted, based on the current branch, please create a new upgrade branch, follow the instructions, using only the referenced versions, including optional steps that match my solution, and normalize all npm scripts to follow best‑practice colon notation.
As a final acceptance run, execute the build command to check for issues: when there are issues, please provide solutions based on facts.
Provide a detailed summary of the applied configuration changes.
In addition to the summary, recommend updates to the documentation based on issues encountered during the upgrade.
Also, make a recommendation for the Microsoft upgrade documentation.업그레이드 프로세스
이 지침은 모든 예방 조치를 포함한 재현 가능한 업그레이드 계획을 제공합니다. 작성자는 Copilot보다 더 신뢰할 수 있는 결과를 제공하므로 업그레이드에 Claude Sonnet 4 사용을 권장합니다.
전체 업그레이드는 15단계 계획을 따르며 사용자 상호작용을 허용합니다. 실행 시간은 일반적으로 몇 분 정도입니다.
업그레이드 중에 Microsoft에서 문서화하지 않은 ESLint 구성 문제를 SPFx package.json 의존성을 비교하여 수동으로 해결했습니다. 작성자는 최소한의 ESLint 구성을 사용했으며, 전체 Microsoft ESLint 파일이 필요하면 다른 보일러플레이트에서 복사하십시오.
평결
전반적으로 AI를 활용한 SPFx 1.22 업그레이드 과정은 거의 완벽하게 작동했습니다. 유일하게 발생한 실제 문제는 Microsoft 공식 업그레이드 가이드에 작은 문서 누락이 있었던 점입니다. 프롬프트 기반 접근 방식은 Claude Sonnet을 사용해 성공적으로 테스트되었습니다.
4 (GitHub Copilot 사용) – 여러 프로젝트와 SPFx 솔루션에 걸쳐
제게 이 AI 지원 업그레이드 흐름은 사용할 가치가 충분합니다. 수동으로 SharePoint Framework를 업그레이드하는 데 몇 시간을 소비하는 대신, Heft와 함께하는 전체 SPFx 마이그레이션을 몇 분 안에 완료할 수 있습니다.
워크플로우에 안전망이 구축되어 있기 때문에, 메인 코드베이스를 위험에 빠뜨리지 않고 언제든지 업그레이드 브랜치를 유지할지 폐기할지 결정할 수 있습니다.
제가 가장 감사하게 생각하는 점은 이 방법이 재현 가능하고 모든 SPFx 프로젝트에 동일한 자동 업그레이드 프로세스를 적용한다는 것입니다. 모든 것이 제대로 문서화되면 Heft와 함께 SPFx 1.22로 업그레이드하는 것이 거의 고민할 필요가 없을 정도로 간단해집니다.