typescript 프로젝트 초기화부터 dist 출력

Typescript 개발환경 셋팅 및 dist 폴더 출력해보기 까지 과정을 진행해보겠다.

 

 1. TypeScript 프로젝트 시작 순서

TypeScript는 그냥 tsc부터 치면 되는 게 아니라,
Node 프로젝트 → TS 도구 설치 → TS 설정 순서가 중요하다.

1. 프로젝트 폴더 생성
2. package.json 생성
3. TypeScript 설치
4. tsconfig.json 생성

 

2. package.json부터 만드는 이유

npm init -y

 

이 명령의 의미는 단순하다.

“이 폴더는 Node.js 프로젝트다”

이걸 먼저 해두면:

• npm / npx가 프로젝트 루트를 정확히 인식
• 이후 설치되는 패키지 버전이 기록됨

3. TypeScript는 개발용(-D)으로 설치

npm install -D typescript

 

이유:

• TypeScript는 런타임에 필요 없음
• 컴파일 단계에서만 사용
• JS로 변환되면 사라짐

"devDependencies": {
  "typescript": "^5.x.x"
}

 

=> TypeScript는 거의 항상 -D가 정답

 

4. npx tsc --init의 정확한 의미

npx tsc --init

 

이 명령은:

“TypeScript 컴파일러에게 이 프로젝트의 기본 설정 파일을 만들어달라”

결과:

tsconfig.json 생성

 

5. 첫 컴파일에서 당황했던 점

npx tsc

 

실행 후 결과:

src/
 ├─ index.ts
 └─ index.js   ← 여기에 생김

 

처음엔

“왜 dist로 안 가고 src에 JS가 생기지?”

라는 의문이 들었다.

 

6. 이유: tsconfig 기본값

TypeScript는 기본적으로 이렇게 동작한다.

“출력 경로가 지정 안 돼 있으면 입력 파일 옆에 JS를 만든다”

즉,

• rootDir, outDir를 안 정했기 때문

7. src / dist 구조로 분리하기

tsconfig.json에 아래 옵션을 추가한다.

{
  "compilerOptions": {
    "rootDir": "src",
    "outDir": "dist"
  }
}

이후 다시 컴파일:

src/
 └─ index.ts
dist/
 └─ index.js

 

8. dist에 파일이 4개 생긴 이유

컴파일 후 dist/를 보면:

dist/
├─ index.js
├─ index.js.map
├─ index.d.ts
└─ index.d.ts.map

 

처음엔 이게 또 의문이었다.

 

9. 생성된 파일들의 역할

index.js

• 실제 실행되는 JavaScript

index.js.map

• 소스맵
• 디버깅 시 TS ↔ JS 라인 매핑

index.d.ts

• 타입 선언 파일
• 이 JS 모듈의 타입 정보

index.d.ts.map

• 타입 선언용 소스맵

이건 에러도 아니고 이상한 상태도 아님

 

10. 왜 d.ts가 생성됐을까?

tsconfig.json에 이런 옵션이 켜져 있었기 때문:

"declaration": true

 

이 옵션은:

• 라이브러리 배포용
• npm 패키지 만들 때 필요

하지만 지금은 앱 개발 / 학습 단계

 

11. 앱 개발 기준 추천 tsconfig

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,
    "declaration": false
  }
}

 

이렇게 하면 결과는:

dist/
├─ index.js
└─ index.js.map