React 프로젝트에서 Node 스크립트를 실행하며 만난 경계

React 프로젝트 안에서 TypeScript 스크립트를 실행하려다 설정 문제에 시간을 썼다. 브라우저에서 잘 되던 import가 Node에서는 다른 결과를 냈고, ES 모듈 문법을 유지하면서 ts-node로 실행하려니 tsconfig의 적용 범위도 살펴봐야 했다. 작은 파일 생성 작업이 실행 환경 점검으로 커진 경험이었다.

같은 언어가 같은 실행 환경은 아니었다

브라우저용 코드는 번들러가 해석한다. Node 스크립트는 Node와 실행 도구가 해석한다. import 경로, 파일 확장자, 모듈 형식이 겉으로 비슷해도 어떤 도구가 최종적으로 읽는지에 따라 조건이 달라진다. 프론트 설정이 맞다는 사실은 스크립트 실행 설정까지 맞다는 보장이 아니었다.

당시에는 require로 되돌리는 대신 ES 모듈 문법을 쓰고 싶었다. 여기서 중요한 것은 문법 취향을 맞추려고 옵션을 하나씩 추가하는 것이 아니라, 프로젝트의 type과 컴파일러의 모듈 설정, 실행 명령이 같은 방향을 가리키는지 확인하는 일이었다.

설정 파일의 범위를 줄이기

스크립트용 설정에서 include를 scripts로 제한하고 불필요한 src를 제외하는 고민도 했다. 이 경계가 없으면 파일 생성 스크립트를 실행하기 위해 UI 쪽 타입과 브라우저 전용 의존성까지 따라가게 된다. 반대로 공유 타입이 필요한데 무조건 분리하면 같은 모델을 두 번 유지하게 된다.

지금이라면 실행 환경에 의존하지 않는 데이터 타입과 순수 변환 함수부터 공유하겠다. 파일 읽기와 쓰기는 Node 쪽에 두고, DOM이나 브라우저 저장소 접근은 UI 쪽에 남기겠다. 같은 저장소에 있다는 이유로 모든 코드를 같은 설정에 넣지는 않겠다.

재현 가능한 명령을 남겼어야 했다

그때 아쉬운 점은 환경 문제를 해결하는 동안 어떤 설정 조합이 최종 기준인지 흐려지기 쉽다는 것이었다. 지금 다시 한다면 Node와 패키지 매니저 버전, 실행 명령, 입력·출력 위치를 짧게 기록하겠다. 누군가 다른 터미널에서 같은 명령을 실행했을 때 같은 파일이 나오는지까지 확인하겠다.

이후 개발 환경을 다룰 때는 에러를 없애는 것과 실행 계약을 정하는 것을 구별한다. 당장 한 번 실행되는 설정보다, 왜 이 설정으로 실행되는지 설명할 수 있는 상태가 더 오래 도움이 됐다.

기술 참고: Node.js ECMAScript modules