Frontend/Typescript

환경 설정 완벽 가이드: Node.js 환경에서 tsconfig.json 설정법 및 개발 환경 구축

미니임 2026. 2. 18. 23:58

TypeScript는 자바스크립트에 '타입'을 더해 개발 생산성과 안정성을 획기적으로 높여줍니다. 하지만 Node.js 환경에서 처음 시작할 때 tsconfig.json의 수많은 옵션 때문에 당황하기 마련입니다. 본 가이드에서는 실무에서 가장 많이 사용하는 설정을 중심으로 단계별 환경 구축법을 설명합니다.

1. 프로젝트 초기 설정 및 패키지 설치

가장 먼저 프로젝트 폴더를 생성하고 필요한 패키지들을 설치해야 합니다.

1.1 프로젝트 초기화

mkdir node-ts-project
cd node-ts-project
npm init -y

1.2 필수 패키지 설치

  • typescript: TypeScript 컴파일러.
  • ts-node: 빌드 없이 직접 .ts 파일을 실행하게 해주는 실행기.
  • nodemon: 파일 수정 시 자동으로 서버를 재시작해주는 도구.
  • @types/node: Node.js 내장 모듈에 대한 타입 정의 파일.
npm install -D typescript ts-node nodemon @types/node

2. tsconfig.json 설정 파헤치기

npx tsc --init 명령어로 기본 파일을 생성할 수 있지만, 아래는 Node.js 백엔드 개발에 최적화된 추천 설정입니다.

[추천] 핵심 설정 예시

{
  "compilerOptions": {
    /* 기본 설정 */
    "target": "ES2022",                // 컴파일될 자바스크립트 버전 (Node 16+ 권장)
    "module": "CommonJS",              // 모듈 시스템 결정 (Node.js 기본은 CommonJS)
    "outDir": "./dist",                // 빌드된 파일이 저장될 경로
    "rootDir": "./src",                // 소스 파일이 위치한 경로
    "lib": ["ES2022"],                 // 컴파일 시 사용할 라이브러리 목록

    /* 엄격한 타입 체크 (강력 권장) */
    "strict": true,                    // 모든 엄격한 타입 체크 옵션 활성화
    "noImplicitAny": true,             // 'any' 타입이 암시적으로 사용되면 에러 발생
    "strictNullChecks": true,          // null 및 undefined 값 체크

    /* 모듈 해석 및 상호 운용성 */
    "moduleResolution": "node",        // Node.js 방식의 모듈 해석
    "baseUrl": ".",                    // 절대 경로 시작점
    "paths": {                         // 경로 별칭 설정
      "@/*": ["src/*"]
    },
    "esModuleInterop": true,           // CommonJS 모듈을 ES 모듈처럼 import 가능하게 함
    "skipLibCheck": true,              // 라이브러리 파일(*.d.ts)의 타입 체크 건너뛰기
    "forceConsistentCasingInFileNames": true // 파일 이름의 대소문자 구분 일치 강제
  },
  "include": ["src/**/*"],             // 컴파일에 포함할 파일 경로
  "exclude": ["node_modules", "dist"]  // 컴파일에서 제외할 파일 경로
}

주요 옵션 상세 설명

  1. target: 작성한 코드가 어느 버전의 JavaScript로 변환될지 결정합니다. 최신 Node.js 버전(18, 20 등)을 사용한다면 ES2022 이상을 사용해도 무방합니다.
  2. module: Node.js는 기본적으로 CommonJS를 사용합니다. 만약 type: "module" (ESM) 방식을 사용한다면 NodeNext로 설정해야 합니다.
  3. esModuleInterop: 중요합니다! 자바스크립트의 moment나 lodash 같은 라이브러리는 CommonJS 방식으로 export되는데, 이를 TypeScript에서 import moment from 'moment'처럼 자연스럽게 쓰게 해줍니다.

3. 효율적인 개발 워크플로우 구축 (package.json)

매번 수동으로 컴파일하고 실행하는 것은 번거롭습니다. package.json에 스크립트를 추가하여 자동화합시다.

{
  "scripts": {
    "start": "node dist/index.js",
    "dev": "nodemon --watch 'src/**/*.ts' --exec 'ts-node' src/index.ts",
    "build": "tsc",
    "clean": "rm -rf dist"
  }
}
  • npm run dev: 개발 중에 코드를 수정하면 자동으로 감지하여 ts-node로 즉시 실행합니다.
  • npm run build: 배포를 위해 TypeScript 코드를 JavaScript로 변환하여 dist 폴더에 저장합니다.

4. 실전 코드 예제 및 프로젝트 구조

권장되는 프로젝트 구조

node-ts-project/
├── src/
│   ├── index.ts
│   └── utils/
│       └── logger.ts
├── tsconfig.json
├── package.json
└── dist/ (빌드 후 생성됨)

코드 예제: src/index.ts

import { logMessage } from './utils/logger';

interface User {
  id: number;
  name: string;
  role: 'admin' | 'user';
}

const welcomeUser = (user: User): string => {
  return `안녕하세요, ${user.name}(${user.role})님! Node.js + TypeScript 환경에 오신 것을 환영합니다.`;
};

const newUser: User = {
  id: 1,
  name: "데브킴",
  role: 'admin'
};

logMessage(welcomeUser(newUser));

5. 마치며: 개발 생산성을 높이는 팁

  1. Strict 모드를 끄지 마세요: 처음에 에러가 많이 발생한다고 strict: false로 두면 TypeScript를 쓰는 의미가 퇴색됩니다. 타입을 정의하는 습관을 들이세요.
  2. @types 검색: 라이브러리를 설치했는데 타입 에러가 난다면, npm install -D @types/라이브러리명을 통해 타입 정의가 있는지 확인하세요.
  3. Path Alias 활용: ../../../../utils 대신 @/utils와 같이 깔끔한 경로를 사용하면 유지보수가 매우 편리해집니다.
반응형