Node 환경에서 module-alias 에러 정리

이 글은 Node 환경에서 JS 파일을 직접 실행할 때 module-alias 관련 에러가 났던 케이스를 짧게 정리한 메모입니다. 특히 TypeScript에서 path alias를 잡아둔 상태라면, 런타임 설정이 안 맞을 때 바로 이런 식으로 터지더라고요.

(node:37877) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
(Use `node --trace-warnings ...` to show where the warning was created)
<project-root>/run-get-components-from-figma-node.js:2
import { FILE_KEY, TOKEN } from '@/figma/constant.js';
^^^^^^

SyntaxError: Cannot use import statement outside a module
    at internalCompileFunction (node:internal/vm:73:18)
    at wrapSafe (node:internal/modules/cjs/loader:1153:20)
    at Module._compile (node:internal/modules/cjs/loader:1205:27)
    at Module._extensions..js (node:internal/modules/cjs/loader:1295:10)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:83:12)
    at node:internal/main/run_main_module:23:47

정리하면 이때 봐야 하는 건 대략 이 정도였습니다.

• package.json의 type 설정
• 실행 대상이 ts-node인지 node인지
• path alias를 빌드 타임만 쓰는지, 런타임에서도 풀어줘야 하는지
• module-alias를 쓴다면 실제 엔트리포인트 전에 등록되는지

저땐 yarn add module-alias로 패키지를 먼저 붙이고, package.json 쪽 alias 설정까지 같이 본 뒤 다시 실행하는 흐름으로 정리했습니다.