jscodeshift로 대규모 코드 리팩토링 자동화하기 🍪

수작업 대체, 스크립트로 코드 바꾸는 시대

프로젝트가 커지고 시간이 흐르다 보면 다음과 같은 일이 잦아집니다.

• API 변경으로 인해 수십 ~ 수백 파일에서 동일한 패턴을 수정해야 한다.
• 단순히 문자열 대체(Find/Replace)로는 놓치는 경우가 생기거나, 실수가 꽤 발생한다.
• 개발팀 내에서 코드 스타일이나 규약을 바꾸고 싶지만, 수작업 부담이 크다.

이럴 때 흔히 사용되는 도구가 codemod입니다. 그 중에서 Facebook(지금은 Meta)의 오픈소스 도구인 jscodeshift는 여러 소스 파일을 AST(추상 구문 트리)를 이용해 변환할 수 있게 설계된 툴입니다. (jscodeshift)
이 글에서는 jscodeshift의 개념부터 설치, 간단한 코드 예제, 실무 적용 팁까지 정리해보겠습니다.

 

1. jscodeshift란 무엇인가?

jscodeshift는 다음 기능을 제공합니다. (jscodeshift)

• 여러 JavaScript/TypeScript 파일에 대해 transform(변환) 스크립트를 실행할 수 있는 러너(runner)를 제공한다.
• 내부적으로는 AST를 이용하여 코드의 구조적 변환을 수행하며, 기존 코드 스타일(들여쓰기, 주석 등)을 최대한 유지하려고 한다.
• 즉, “코드를 다시 작성하는 스크립트”를 만들 수 있게 해주는 도구입니다.

“정규 표현식 기반 찾기·바꾸기가 한계가 있다면, jscodeshift로 AST 기반 변환을 도입해야 한다”는 논의도 많습니다. (toptal.com)

 

2. 왜 도입해야 하나? 언제 유용한가?

아래와 같은 상황에서 특히 jscodeshift가 빛을 발합니다.

• API가 변경되었다. 외부 라이브러리 함수명이나 인자 구조가 바뀌었고, 프로젝트 전반에서 이를 교체해야 한다.
• 코드 스타일을 대대적으로 변경해야 한다. 예를 들어 클래스형 컴포넌트 → 함수형 컴포넌트로 일괄 전환한다거나.
• Team-wide 규약이 바뀌었다. 예를 들어 import 경로나 파일명 규칙, 특정 함수 사용 금지 등이 생긴 경우.
• 반복적이고 위험한 수작업을 줄이고 자동화로 신뢰성 있게 처리하고자 할 때.

Widen Engineering 블로그에서는 이렇게 말한다.

“거대한 JS 생태계에서, 수작업으로 리팩토링만 한다면 시간이 많이 들고 실수 가능성도 크다. jscodeshift로 코드 변환을 자동화하면 그러한 비용을 크게 줄일 수 있다.” (pkerschbaum.com)

3. 설치 및 기본 사용법

설치해보기

npm install -g jscodeshift

위 명령으로 전역 설치하면 jscodeshift 커맨드를 사용할 수 있습니다.

 

변환 스크립트(Transform) 기본 구조

// transform.js
module.exports = function(fileInfo, api, options) {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  // 여기서 AST 탐색 + 변환 로직 작성

  return root.toSource();
};

위 구조는 Feifan Zhou의 블로그에서도 처음 단계로 소개됩니다.

 

CLI 실행 예

jscodeshift -t transform.js src/ --extensions=js,tsx --parser=tsx

위 명령은 src/ 디렉토리 이하의 .js/.tsx 파일들을 transform.js 변환 스크립트로 처리합니다.

 

4. 간단한 코드 예제

예를 들어 “변수명 foo를 bar로 바꾸자”라는 아주 단순한 변환을 작성해보겠습니다.

// rename-foo-to-bar.js
module.exports = function(fileInfo, api) {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  return root
    .find(j.Identifier, { name: 'foo' })
    .replaceWith(path => j.identifier('bar'))
    .toSource({ quote: 'single' });
};

이후

jscodeshift -t rename-foo-to-bar.js src/

위와 같이 실행하면 foo라는 식별자가 있는 코드가 모두 bar로 바뀝니다.
이런 단순 예제를 통해 “AST 탐색 → 노드 교체 → 코드 생성” 흐름을 이해할 수 있습니다. (saltycrane.com)

 

5. 실무 적용 팁 및 주의사항

✅ 구조 설계

• 변환 범위 정의: 어느 디렉토리, 어느 파일 형식까지 변환할지 명확히 합니다 (--extensions, --ignore-config). (jscodeshift)
• dry-run 먼저 수행: -d 옵션(변경 없이 출력) 또는 --print 옵션으로 결과를 확인한 뒤 실제 반영하세요. (feifan.blog)
• 테스트 케이블 준비: 수정 전/후 결과를 비교할 테스트 스위트를 함께 두는 것이 좋습니다. jscodeshift 자체도 Jest 기반 테스트를 지원합니다. (toptal.com)

⚠️ 주의사항

• AST 기반 변환임에도 복잡한 코드 구조(예: 동적 import, 템플릿 리터럴 복잡한 경우)에서는 의도치 않은 결과가 나올 가능성이 있습니다.
• 원본 코드 스타일(주석, 줄바꿈, 들여쓰기 등)이 변환 후 달라질 수 있으므로 스타일 유지 옵션을 잘 검토해주세요. (Hypermod)
• 변환 후에는 반드시 리뷰 및 QA 절차를 거쳐야 합니다.

실무 유의점

• 팀 내에서 자동 변환 스크립트 사용 시 “언제, 왜” 이 리팩토링을 했는지 기록해두는 것이 좋습니다. (martinfowler.com)
• 오픈소스 라이브러리처럼 다수의 외부 사용자가 있는 코드베이스에서는 변경 로그와 커뮤니케이션도 중요합니다.

 

6. 마무리 및 기억해야 할 것

• jscodeshift는 거대한 코드베이스를 리팩토링하거나 규약을 바꿀 때 매우 유용한 도구입니다.
• AST(추상 구문 트리)를 활용하여 “코드 그 자체를 코드로 바꾸는” 방식으로 수작업의 한계를 극복할 수 있습니다.
• 하지만 자동화라 해서 무조건 안전한 것은 아니며, dry-run, 테스트, 리뷰라는 절차는 반드시 필요합니다.
• 잘 설계된 codemod는 팀 생산성을 크게 향상시킬 수 있으나, 잘못 설계되면 코드 품질에 해가 될 수 있습니다.

 

참고 자료

• jscodeshift 공식 문서: https://jscodeshift.com/overview/introduction
• Toptal – “Write Code to Rewrite Your Code: jscodeshift”: https://www.toptal.com/javascript/write-code-to-rewrite-your-code
• Martin Fowler – “Refactoring Code with Codemods to Automate API Changes”: https://martinfowler.com/articles/codemods-api-refactoring.html