TypeScript 개발 명령어 핸드북

반응형

 

TypeScript 개발 명령어 핸드북

 

📚 목차
1. TypeScript 설치 및 초기화
2. 컴파일(Build) vs 타입 체크(Type-Check)
3. TypeScript 파일 직접 실행 (tsx vs ts-node)
4. 스크립트 템플릿 예시

 

TypeScript 명령어 삽화 이미지

 

1. TypeScript 설치 및 초기화

글로벌 설치보다는 프로젝트별 버전 고정 및 협업 일관성을 위해 개발 의존성(devDependencies) 설치를 권장합니다.

 

🔷 설치 및 초기화

npm install -D typescript  # 1. 패키지 설치
npx tsc --version          # 2. 설치 버전 확인
npx tsc --init             # 3. tsconfig.json 생성

 

🔷 tsconfig.json 핵심 옵션 예시

{
  "compilerOptions": {
    "target": "ES2022",                    // 변환할 JavaScript 버전. Node.js 18 이상 환경에 적합
    "module": "ESNext",                    // import/export 문법을 사용하는 ESM 방식
                                           
    "moduleResolution": "bundler",         // import한 파일을 찾는 방식
    "lib": ["ES2022"],                     // 사용할 JavaScript 기본 기능 타입. Promise, Map, Set 등 포함
    "types": ["node"],                     // Node.js 타입 사용. process, Buffer 같은 전역 객체 인식

    "rootDir": "src",                      // TypeScript 소스 루트 폴더
    "outDir": "dist",                      // 컴파일 결과물 출력 폴더

    "strict": true,                        // 엄격한 타입 검사 활성화
    "exactOptionalPropertyTypes": true,    // 선택 속성(?)과 undefined 값을 구분해서 검사
    "isolatedModules": true,               // 각 파일을 독립적으로 컴파일 가능한 모듈로 처리
    "skipLibCheck": true,                  // node_modules의 타입 선언 파일 검사 생략

    "verbatimModuleSyntax": true,          // import/export 문법을 TypeScript가 임의로 바꾸지 않게 함
    "noUncheckedSideEffectImports": true,  // import "./파일" 형태의 경로 오타를 더 잘 잡아줌
    "moduleDetection": "force",            // 모든 파일을 모듈로 처리해 전역 변수 충돌 방지

    "sourceMap": true,                     // 에러 발생 시 원본 .ts 파일 위치를 추적할 수 있게 함
    "declaration": false,                  // .d.ts 타입 선언 파일 생성 안 함. 백엔드 앱에서는 보통 불필요
    "declarationMap": false                // .d.ts.map 파일 생성 안 함
  },
  "include": ["src/**/*.ts"],              // src 폴더 아래의 모든 .ts 파일을 검사/빌드 대상으로 포함
  "exclude": ["node_modules", "dist"]      // 타입 검사에서 제외할 경로. 의존성 및 빌드 결과물 제외
}

 

 

2. 컴파일(Build) vs 타입 체크(Type-Check)

🔷 타입 체크 전용 (Type-Check)

--noEmit 옵션을 추가하면 컴파일 결과물(.js, .d.ts 등)을 디스크에 쓰지 않고 메모리상에서 타입 검사만 수행합니다. 

빌드 프로세스 전 단계나 CI/CD 파이프라인에서 필수적으로 사용됩니다.

# 타입 체크만 (파일 생성 안 함)
npx tsc --noEmit
npx tsc --noEmit -p tsconfig.json              # 특정 설정 지정
npx tsc --noEmit -p sub-project/tsconfig.json  # 하위 프로젝트

 

🔷 기본 컴파일 (Build)

tsconfig.json 설정을 바탕으로 .ts 파일을 .js 파일로 변환합니다.

# 기본 컴파일 (tsconfig.json 기준)
npx tsc

# 특정 파일만 단독 컴파일 (실무에서는 자주 쓰이지 않음)
npx tsc src/index.ts

# 특정 프로젝트 설정 파일 지정 컴파일 (권장)
npx tsc -p tsconfig.json

 

🔷 Watch 모드

파일 변경을 감지하여 자동으로 다시 컴파일한다.

# 코드 변경 시마다 자동으로 빌드(JS 파일 생성)를 다시 수행
npx tsc --watch (또는 npx tsc -w)

# 컴파일 없이, 코드 변경 시마다 실시간으로 타입 에러만 감지 (리소스 절약)
npx tsc --noEmit --watch

 

🔷 문제 분석 명령어

npx tsc --showConfig -p tsconfig.json   # 최종 적용 설정 확인
npx tsc --noEmit --listFiles            # 컴파일 대상 파일 목록
npx tsc --noEmit --traceResolution      # import 경로 해석 과정 추적

반응형

 

3. TypeScript 파일 직접 실행 (tsx vs ts-node)

TypeScript는 Node.js에서 바로 실행할 수 없으므로, 개발 단계에서는 변환과 실행을 동시에 해주는 도구를 사용합니다. 최신 개발 환경에서는 속도가 빠르고 설정이 간편한 tsx를 권장합니다.

 

🔷 Option A: tsx (추천)

# 설치
npm install -D tsx

# 단발성 실행
npx tsx src/index.ts

# Watch 모드로 실행 (코드 수정 시 자동 재시작)
npx tsx watch src/index.ts

 

🔷 Option B: ts-node (기존 프로젝트/스크립트용)

# 설치
npm install -D ts-node

# 실행
npx ts-node src/index.ts

 

4. 스크립트 템플릿 예시

🔷 단일 백엔드 프로젝트 (Fastify 예시)

fastify-api-rest/
├─ src/
│  └─ server.ts
├─ dist/
├─ package.json
└─ tsconfig.json

# package.json 
# 빌드 전 이전 출력물을 지우기 위해 rimraf를 활용하는 clean 패턴을 포함합니다
{
  "scripts": {
    // 개발 서버 실행, TypeScript 파일 변경 시 자동 재시작
    "dev": "tsx watch src/server.ts",

    // 타입 검사만 수행, JavaScript 파일은 생성하지 않음
    "typecheck": "tsc --noEmit -p tsconfig.json",

    // TypeScript를 JavaScript로 컴파일
    "build": "tsc -p tsconfig.json",

    // 빌드된 JavaScript 서버 실행
    "start": "node dist/server.js",

    // 이전 빌드 결과물인 dist 폴더 삭제
    "clean": "rimraf dist",

    // dist 삭제 후 다시 빌드
    "rebuild": "npm run clean && npm run build",

    // ESLint로 코드 스타일과 잠재적 문제 검사
    "lint": "eslint .",

    // 테스트를 한 번 실행하고 종료
    "test": "vitest run",

    // 커밋 전 확인용
    // 타입 검사 후 린트 실행
    "check": "npm run typecheck && npm run lint",

    // CI 검증용
    // 린트, 타입 검사, 테스트 순서로 실행
    "ci": "npm run lint && npm run typecheck && npm run test"
  }
}

▸ npm run dev: 소스 변경을 감지하여 즉시 로컬 API 서버를 재시작합니다.
▸ npm run typecheck: 결과물 생성 없이 설정 파일 기준으로 타입 검사만 수행합니다.
▸ npm run build: 기존 dist 디렉터리를 깔끔하게 지우고 새로 빌드 결과물을 생성합니다.

 

🔷 모노레포 / 하위 프로젝트 구조

workspace/
├─ fastify-api-rest/
│  ├─ src/
│  └─ tsconfig.json
├─ web-app/
│  ├─ src/
│  └─ tsconfig.json
└─ package.json

# 루트 package.json 
{
  "scripts": {
    "typecheck:api": "tsc --noEmit -p api/tsconfig.json",
    "build:api": "tsc -p api/tsconfig.json",
    "typecheck:web": "tsc --noEmit -p web/tsconfig.json",
    "build:web": "tsc -p web/tsconfig.json"
  }
}

---

※ 게시된 글 및 이미지 중 일부는 AI 도구의 도움을 받아 생성되거나 다듬어졌습니다.

반응형