Node에서 Bun으로의 마이그레이션을 bun-runtime 스킬로 에이전트에게 맡기기
機械翻訳 / Machine-translated

機械翻訳 / Machine-translated
원문: Node에서 Bun으로의 마이그레이션을 bun-runtime 스킬로 에이전트에게 맡기기(cccskills)
스킬 페이지: bun-runtime
이 글의 결론
bun-runtime을 설치하면 실행·의존 패키지 관리·빌드·bun test를 이용한 테스트·Vercel 설정까지 Bun 기반으로 AI 에이전트가 진행해줍니다.
JavaScript나 TypeScript로 개발하는 분을 위한 스킬입니다.
Node에서의 교체 방법, 설치 방법, 요청문 예시, 마이그레이션 전후에 확인할 사항을 순서대로 소개합니다.
bun-runtime을 설치하면 Node로 동작하는 프로젝트의 실행·의존 관리·테스트를 Bun 기반으로 에이전트가 교체해줍니다.
요청 예시는 다음과 같습니다.
이 Node 프로젝트를 Bun으로 마이그레이션해줘.
테스트도 bun test로 동작하게 해줘
에이전트는 스킬의 마이그레이션 절차에 따라 node나 npm으로 작성된 명령어를 Bun 명령어로 교체합니다.
의존 패키지는 bun install로 재설치되고, 텍스트 형식의 락 파일 bun.lock이 생성됩니다.
교체 대응표는 다음과 같습니다.
| Node·npm 작성 방식 | Bun 작성 방식 |
|---|---|
| node script.js | bun run script.js 또는 bun script.js |
| npm install | bun install |
| npm run dev | bun run dev |
| npx를 이용한 단발 실행 | bun x |
테스트는 bun:test에서 expect와 test를 불러오는 형식으로 작성됩니다.
API가 Jest와 유사하므로 작성 방법을 처음부터 다시 익힐 필요는 없습니다.
bun-runtime은 Bun을 런타임(프로그램을 실행하는 환경), 패키지 매니저, 번들러, 테스트 러너의 4가지 역할로 사용하기 위한 절차서입니다.
실행부터 배포용 빌드까지를 하나의 도구로 갖출 수 있으므로, 에이전트에게 같은 방식으로 작업시킬 수 있습니다.
스킬에는 Bun과 Node 중 어느 것을 선택할지에 대한 기준도 포함되어 있습니다.
고민될 때의 판단 기준은 다음 표와 같습니다.
| 선택 | 적합한 상황 |
|---|---|
| Bun | 새로운 JS·TS 프로젝트, 설치나 실행 속도가 중요한 스크립트, Bun 런타임에서의 Vercel 배포, 실행·설치·테스트·빌드를 하나로 통합하고 싶을 때 |
| Node | 에코시스템과의 호환성을 최우선으로 할 때, Node 전제의 오래된 도구, Bun에서 알려진 문제가 있는 의존 패키지를 사용할 때 |
TypeScript 파일은 bun src/index.ts처럼 그대로 실행할 수 있습니다.
의존 추가·삭제·업데이트는 bun add, bun remove, bun update로 수행하며, 오래된 것은 bun outdated로 목록을 확인합니다.
.env 파일을 불러와서 실행하는 방식도 스킬의 범위에 포함됩니다.
여러 패키지를 하나의 저장소에 모은 모노레포에도 대응합니다.
package.json에 workspaces를 나열하는 방식은 npm이나 yarn과 동일합니다.
특정 패키지에서만 스크립트를 실행할 때는 bun run --filter를 사용합니다.
파일 읽기/쓰기·HTTP 서버·SQLite·SQL 데이터베이스·Redis·S3 호환 스토리지는 Bun의 내장 기능으로 작성할 수 있습니다.
외부 패키지를 추가하기 전에 먼저 내장 기능으로 해결하는 것이 스킬의 방침입니다.
내장 번들러와 트랜스파일러를 사용해 앱이나 라이브러리를 배포용으로 묶습니다.
빌드는 bun run build 또는 bun build ./src/index.ts --outdir=dist 형식으로 실행합니다.
모든 테스트를 실행하는 명령어는 bun test입니다.
--watch를 붙이면 파일 변경에 맞춰 재실행됩니다.
CI용으로는 Bun 1.4에서 사용할 수 있는 옵션도 정리되어 있습니다.
| 옵션 | 용도 |
|---|---|
| --changed | 변경의 영향을 받는 테스트만 실행 |
| --parallel | 워커 프로세스로 병렬 실행 |
| --shard=<n>/<count> | CI에서 테스트를 분할해서 실행 |
| --isolate | 파일마다 새로운 전역 환경에서 실행 |
Vercel에서는 vercel.json에 bunVersion을 작성해 Bun 1.4를 지정합니다.
배포 시 설치는 bun install --frozen-lockfile로 수행하며, 락 파일 그대로의 의존을 재현합니다.
{
"bunVersion": "1.4.x"
}
설치에 필요한 것은 명령어 한 줄뿐입니다.
npx skills add에서는 Claude Code나 Codex 등 설치할 에이전트를 선택할 수 있습니다.
npx skills add https://github.com/affaan-m/ECC --skill bun-runtime
에이전트에게 설치를 요청하는 경우에는 다음 문장을 그대로 보내주세요.
次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/bun-runtime
まず SKILL.md と付属ファイルの中身を確認し、不審な処理(外部への送信、認証情報の読み取りなど)がないことを確かめてから、Claude Code なら ~/.claude/skills/bun-runtime/、Codex なら ~/.agents/skills/bun-runtime/ に配置してください。
저장 위치는 모든 프로젝트에서 사용할지, 특정 프로젝트에서만 사용할지에 따라 달라집니다.
| 에이전트 | 모든 프로젝트에서 사용 | 특정 프로젝트에서만 사용 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 프로젝트의 .claude/skills/ |
| Codex | ~/.agents/skills/ | 프로젝트의 .agents/skills/ |
포함된 파일은 SKILL.md 하나뿐입니다.
배포처는 affaan-m/ECC이며, 라이선스는 MIT입니다.
대표적인 사용 방법은 새 프로젝트 시작, 기존 프로젝트 마이그레이션, 테스트와 배포 설정의 세 가지입니다.
TypeScript로 API 서버를 새로 만들고 싶어.
Bun으로 시작하고, 테스트와 빌드 설정도 넣어줘
이 요청에서는 Bun.serve를 사용한 HTTP 서버와 bun:test로 작성한 테스트 파일이 준비됩니다.
의존은 bun install로 설치되고, 빌드는 bun build로 dist에 출력하는 형식입니다.
이 Node 프로젝트를 Bun으로 마이그레이션하는 절차와 호환성 확인 사항을 정리해줘
돌아오는 것은 스크립트 교체 대응표와 bun install로 락 파일을 만드는 절차입니다.
아울러, 네이티브 확장이나 Node 고유의 내부 기능에 의존하는 패키지가 확인 사항으로 제시됩니다.
bun test로 테스트를 작성하고, Vercel용 빌드 설정을 준비해줘
테스트 파일과 bunVersion을 지정한 vercel.json이 갖춰집니다.
배포 시 절차는 bun install --frozen-lockfile과 bun run build를 사용하는 형식입니다.
이 스킬은 Bun 명령어를 사용하는 절차서이므로, 로컬에 Bun 본체가 설치되어 있어야 합니다.
절차는 Bun 1.4.x를 기준으로 합니다.
CLI 플래그는 버전마다 변경될 수 있으므로, bun --version으로 버전을 확인한 후 사용해주세요.
Bun의 Node 호환성은 완전하지 않습니다.
일부 네이티브 확장, 잘 사용되지 않는 node: 내부 API, Node 고유의 내부에 의존하는 패키지는 실패할 수 있습니다.
마이그레이션 후에는 반드시 테스트를 실행하고, 프로덕션에서 사용하기 전에 동작을 확인해주세요.
의존 조작에도 주의가 필요합니다.
bun audit는 bun.lock에 있는 패키지명과 버전을 레지스트리에 조회합니다.
사내 비공개 패키지가 있는 경우 전송처를 확인해주세요.
bun audit fix는 의존을 업데이트하고 재설치하는 명령어입니다.
따라서 락 파일과 설치된 패키지가 변경됩니다.
--isolate는 파일마다 전역 환경을 분리할 뿐이며, 프로세스나 보안의 샌드박스가 아닙니다.
Vercel 설정은 vercel.json의 내용을 확인한 후 적용해주세요.
스킬 자체도 설치하기 전에 SKILL.md의 내용을 읽어두면 안심할 수 있습니다.
아닙니다.
대부분의 패키지는 동작하지만, 호환성이 100%는 아닙니다.
네이티브 확장이나 Node 고유의 내부 기능에 의존하는 패키지는 마이그레이션 전에 검증이 필요합니다.
현재 Bun의 표준은 텍스트 형식의 bun.lock입니다.
오래된 바이너리 형식의 bun.lockb도 마이그레이션을 위해 읽어들일 수 있습니다.
새 프로젝트에서 사용하는 것은 bun.lock입니다.
네.
동일한 의존을 재현하기 위해 bun.lock을 커밋하는 것이 스킬의 베스트 프랙티스로 제시되어 있습니다.
Vercel에서는 --frozen-lockfile과 조합하는 형식입니다.
절차는 Bun 1.4.x를 기준으로 작성되어 있습니다.
다른 버전에서 사용할 때는 설치한 버전의 도움말이나 문서에서 플래그 지원 여부를 확인해주세요.
bun-runtime은 Bun에서의 실행·의존 관리·빌드·테스트·Vercel 설정을 하나로 묶은 절차서입니다.
Node에서의 마이그레이션에서는 명령어 교체와 호환성 확인 사항을 에이전트가 정리해줍니다.
단, 마이그레이션 후의 테스트 실행과 vercel.json 확인만큼은 직접 수행해주세요.
자세한 내용은 cccskills 페이지를 참조해주세요.
이 글은 cccskills의 읽을거리 「Node에서 Bun으로의 마이그레이션을 bun-runtime 스킬로 에이전트에게 맡기기」의 전재입니다.
스킬의 상세 내용과 설치 방법은 cccskills의 bun-runtime 페이지에 있습니다.