Node.js와 TypeScript 통합 베스트 프랙티스

소개

Node.js와 TypeScript를 통합하면 타입 안정성과 생산성을 동시에 얻는다. 처음에는 설정이 복잡해 보이지만 핵심 원칙을 알면 유지보수와 확장이 쉬워진다. 이 글은 Node.js TypeScript 설정, ts-node 프로젝트 구성, TypeScript Node 빌드 설정을 중심으로 실무에 바로 적용 가능한 구성과 설명을 제공한다.

프로젝트 초기화

프로젝트 시작 시 기본 파일과 의존성을 정리한다. 개발 의존성으로는 typescript, ts-node(또는 ts-node-dev), @types/node, eslint, prettier 등을 권장한다.

예제: 기본 설치

npm init -y
npm install -D typescript ts-node ts-node-dev @types/node eslint prettier

파일 구조 예시

• src/ - 소스 코드
• dist/ - 빌드 결과물
• tsconfig.json
• package.json

tsconfig.json 핵심 설정

타깃 환경과 모듈 시스템을 명확히 해야 한다. Node 14+ 또는 최신 환경에서는 ES 모듈 설정을 고려하고, CommonJS 환경이 필요하면 module을 "CommonJS"로 둔다.

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "outDir": "dist",
    "rootDir": "src",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "declaration": true
  },
  "include": ["src"]
}

위 설정은 안정성과 호환성을 중심으로 한 기본값이다. ES 모듈을 사용하면 "module": "ESNext"와 package.json에 "type": "module"을 추가한다.

개발 환경: ts-node와 ts-node-dev

빠른 개발 사이클을 위해 ts-node 또는 ts-node-dev를 사용한다. ts-node는 런타임에서 TypeScript를 실행하고, ts-node-dev는 변경 감지 후 재시작을 자동화한다. ts-node 프로젝트 구성 시 source maps를 활성화하면 디버그가 편해진다.

"scripts": {
  "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
  "start": "node dist/index.js",
  "build": "tsc -p tsconfig.json"
}

빌드 설정과 배포 흐름

개발 중에는 ts-node로 빠르게 확인하고, 배포는 tsc로 컴파일한 결과물을 배포한다. 빌드 파이프라인에는 lint, test, build, pack 순서를 두는 것이 일반적이다.

CI 예시 단계:
1. npm ci
2. npm run lint
3. npm test
4. npm run build
5. 배포(서버에 dist 업로드 또는 컨테이너 이미지 생성)

TypeScript Node 빌드 설정에서 중요한 점은 sourceMap과 declaration 설정이다. sourceMap은 런타임 에러 분석에 도움이 되고, declaration(.d.ts)은 라이브러리로 배포할 때 필요하다.

모듈 경로와 alias

프로젝트가 커지면 상대 경로가 번거롭다. tsconfig의 paths를 이용해 alias를 정의하고, 런타임에서도 동작하게 하려면 tsconfig-paths 같은 도구를 사용한다.

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

테스트, 린트, 타입 검사

타입 검사는 빌드 과정에서 자동으로 실행되지만, 빠른 피드백을 위해 CI에서는 별도 타입 검사 명령을 둔다. ESLint와 Prettier를 연동하면 코드 일관성을 유지할 수 있다. 테스트는 ts-jest 또는 vitest 같은 도구를 통해 TypeScript로 바로 실행한다.

성능과 트랜스파일 옵션

개발 중 속도를 위해 --transpile-only 옵션을 사용하면 타입 검사 없이 빠르게 실행한다. 다만 배포 전에는 항상 정적 타입 검사를 실행해 오류를 방지한다. 대규모 프로젝트는 incremental 빌드와 composite 프로젝트를 고려하면 빌드 시간이 크게 줄어든다.

결론 및 체크리스트

• tsconfig 기본값을 프로젝트 요구사항에 맞춰 정리
• 개발은 ts-node/ts-node-dev, 배포는 tsc 컴파일 결과물 사용
• sourceMap, declaration 설정으로 디버그와 배포 지원
• 모듈 alias는 paths와 런타임 도구로 연결
• CI에서 lint, test, build 순서로 검증

이 구조를 따르면 Node.js TypeScript 설정과 ts-node 프로젝트 구성, TypeScript Node 빌드 설정이 명확해진다. 처음 접하는 단계에서도 위 체크리스트와 예제를 따라가면 안정적인 통합 환경을 만들 수 있다.