트랜스파일에서 문법 오류 경로 문제 빌드 환경

트랜스파일은 최신 JavaScript 문법이나 프레임워크 코드(JSX, TS 등)를 구형 환경에서도 실행 가능하도록 변환하는 과정입니다. 하지만 이 과정에서 다양한 오류가 발생할 수 있으며, 이를 제대로 이해하고 처리하지 않으면 개발 흐름이 크게 지연될 수 있습니다. 본 글에서는 Babel, TypeScript, SWC 등 주요 트랜스파일러 환경에서 자주 발생하는 오류 유형과 그에 대한 실전 대처법을 정리합니다.

문법 오류 및 플러그인 미설정 문제

트랜스파일 오류의 가장 흔한 원인은 설정되지 않은 문법 처리입니다. 예를 들어, Babel에서 ES6 이상 문법을 사용하는데도 플러그인이 누락된 경우 다음과 같은 오류가 발생할 수 있습니다:

SyntaxError: Unexpected token '...'

이런 경우 @babel/preset-env 또는 해당 문법에 맞는 플러그인을 추가해야 합니다:

npm install --save-dev @babel/preset-env

babel.config.js에 다음과 같이 설정합니다:

module.exports = {
  presets: ['@babel/preset-env'],
};

TypeScript에서는 target 설정이 낮으면 ES6 이상의 문법에서 오류가 발생할 수 있습니다. 예:

{
  "compilerOptions": {
    "target": "ES5",
    "lib": ["ES6", "DOM"],
    ...
  }
}

또한 JSX 사용 시 @babel/preset-react 또는 tsconfig.json의 jsx 설정이 없으면 컴파일 오류가 발생하므로, 항상 프로젝트에 맞는 preset과 옵션을 확인해야 합니다.

모듈 해석 오류와 경로 문제

트랜스파일 환경에서는 모듈 해석 방식이 중요한데, 잘못된 경로나 잘못된 import 방식으로 인해 다음과 같은 오류가 자주 발생합니다:

Cannot find module './utils/helper'

이 오류의 주요 원인은 다음과 같습니다:

• 실제 파일 경로 오탈자 (.js 누락, 대소문자 불일치 등)
• alias 설정 누락 (예: Webpack의 resolve.alias, TS의 paths)
• 확장자 생략으로 인한 인식 불가

TypeScript의 경우 paths와 baseUrl 설정을 활용해 다음과 같이 정리할 수 있습니다:

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@utils/*": ["utils/*"]
    }
  }
}

Webpack 또는 Babel도 동일하게 module-resolver 플러그인을 사용해 경로 alias를 지정할 수 있으며, 이 설정이 일관되지 않으면 트랜스파일이 실패합니다. 이와 함께 ESLint와 Prettier 등의 도구에서도 동일한 alias 설정을 유지해야 충돌 없이 작동합니다.

빌드 환경 및 버전 충돌 오류

트랜스파일러는 빌드 도구, 패키지 매니저, Node.js 환경 등 다양한 요소에 영향을 받기 때문에, 버전 충돌이나 설정 불일치로 인한 오류도 잦습니다. 다음은 대표적인 오류 예시입니다:

Error: Plugin/Preset files are not allowed to export objects, only functions.

이 오류는 Babel 7 이상에서 예전 preset을 사용하는 경우 발생하며, 다음과 같이 최신 preset 버전을 명시적으로 설치해야 해결됩니다:

npm install --save-dev @babel/preset-env@latest

또한 TypeScript와 Babel을 함께 사용할 경우, tsconfig.json과 babel.config.js가 충돌하는 설정을 가지고 있으면 의도치 않은 트랜스파일 결과가 나올 수 있습니다. 예를 들어, TypeScript가 이미 ES5로 변환한 코드를 Babel이 다시 변환하려고 하면서 오류가 발생합니다.

이 문제는 보통 다음과 같은 방식으로 해결할 수 있습니다:

• TypeScript는 타입만 검사하고 Babel이 코드 변환을 담당하게 구성
• ts-loader 대신 babel-loader와 @babel/preset-typescript 조합 사용

SWC와 같은 최신 트랜스파일러 도입 시에도 .swcrc 설정 파일을 정확히 구성하고, Babel preset과의 호환성을 검토해야 합니다.

트랜스파일 과정에서 발생하는 오류는 대부분 설정 오류, 문법 미지원, 경로 문제 또는 환경 충돌로 인해 발생합니다. 따라서 트랜스파일러의 역할과 구조를 정확히 이해하고, preset/plugin 설정을 명확히 구성하는 것이 중요합니다. 실시간 트랜스파일 테스트 환경(Vite, tsx 등)을 통해 빠르게 문제를 재현하고 해결하는 습관도 생산성을 높이는 데 큰 도움이 됩니다.