[환경구성] tsconfig.js, tsc

 

tsconfig.json (혹은 tsconfig.ts)

 : TypeScript 컴파일러에 프로젝트의 설정(컴파일 옵션, 포함할 파일, 제외할 파일 등)을 알려주는 구성 파일입니다.

 

• 주요 역할:
  • 컴파일 옵션 설정: 예를 들어, ECMAScript 버전(target), 모듈 시스템(module), 엄격한 타입 검사(strict) 등.
  • 프로젝트 파일 지정: 어떤 파일들을 컴파일할지 포함(include) 및 제외(exclude)할 파일들을 지정.

 

tsc (TypeScript Compiler)

 : TypeScript 소스 코드를 JavaScript로 컴파일하는 명령줄 도구입니다.

 

• 주요 역할:
  • 컴파일 실행: 프로젝트 루트에 tsconfig.json이 있으면, 그 설정에 따라 전체 프로젝트를 컴파일합니다.
  • 파일 단위 컴파일: tsconfig.json 없이 단일 파일을 컴파일할 수도 있습니다.

 

• 사용 방법:
  터미널에서 tsc 명령을 실행하면, 기본적으로 tsconfig.json을 읽어서 TypeScript 파일들을 컴파일합니다.

 

 

tsc: tsconfig 설정에 따른 전체 프로젝트 컴파일

tsc [파일명]: 단일 파일 컴파일

tsc --init: 기본 tsconfig.json 생성

tsc -w: 변경 감지 후 자동 컴파일

tsc -p [경로]: 특정 tsconfig.json을 사용하여 컴파일

tsc -b: 프로젝트 참조를 사용하는 빌드 모드

 

 

---

 

 

{
  //다중 프로젝트를 구성할 때, 다른 프로젝트(tsconfig)를 참조할 수 있게 해줍니다.
  "references": [
    { "path": "./core" },
    { "path": "./ui" }
  ]
  
  //다른 tsconfig 파일의 설정을 상속하여 재사용할 수 있습니다
  "extends": "./tsconfig.base.json"
 
  
  //컴파일에 포함할 파일들을 명시적으로 나열합니다.
  "files" : []
  
  //컴파일에서 제외할 파일이나 디렉토리를 지정합니다.
  "exclude" : []
  
  //컴파일 대상 파일들의 glob 패턴 목록을 지정합니다.
  "include": [
    "**/*",
    "**/.client/**/*",
    ".react-router/types/**/*"
  ],
  "compilerOptions": {
    
    //컴파일 시 포함할 라이브러리 파일들의 목록
    "lib": ["DOM", "DOM.Iterable", "ES2022"],
    
    //import 안해도 사용가능
    //전역으로 포함할 타입 선언 패키지(@types/...)를 지정합니다.
    "types": ["node", "vite/client"],
    
    //설명: 컴파일 후 생성되는 JavaScript 코드의 ECMAScript 버전을 지정합니다.
    //예: "ES5", "ES6", "ES2017", "ESNext"
    "target": "ES2022",
    
    //TypeScript가 어떤 모듈 시스템을 사용하여 변환할지를 결정합니다.
    //예를 들어, module을 "commonjs"로 설정하면, TypeScript는 require와 module.exports를 사용하는 방식으로 변환됩니다.
    "module": "ES2022",
    
    //allowJs & checkJs
    //JavaScript 파일을 TypeScript 프로젝트에 포함할지 여부를 결정합니다.
    "allowJs" : true, 
    
    //JavaScript 파일에 대해 타입 검사를 할지 여부를 결정합니다.
    "checkJs" : true,
    
    //"outDir" : 컴파일된 파일들이 출력될 디렉토리를 지정합니다.
    "outDir" : ".dist"
    
    //모듈 해석 방식을 설정합니다.
    "moduleResolution": "bundler",
    
    //JSX 코드가 컴파일될 방식을 지정합니다.
    //"preserve": JSX 구문을 그대로 유지합니다. (후처리 필요)
    //"react": React.createElement 호출로 변환 (구식 변환)
    //"react-jsx": React 17+의 새로운 JSX 변환 방식
    //"react-jsxdev": 개발용 React 17+ JSX 변환 방식
    "jsx": "react-jsx",
    
    //소스 파일들의 루트 디렉토리를 지정합니다.
    "rootDirs": [".", "./.react-router/types"],
    
    //비상대적 모듈(예: import { foo } from "foo";)의 경로 해석 시 기준이 되는 디렉토리를 지정합니다.
    "baseUrl": ".",
    
    //모듈 이름 별칭을 정의하여, 특정 모듈 경로를 다른 경로로 매핑할 수 있게 합니다.
    "paths": {
      "@/*": ["./src/*"],
      "@assets/*": ["../../resources/_assets/*"]
    },
    
    //CommonJS 모듈을 ES 모듈처럼 default import 할 수 있도록 도와줍니다.
    "esModuleInterop": true,
    
    //true : (예: import, export, require) 번들러가 해석하도록
    //컴파일러가 모듈 구문(예: import, export, require)을 원본 소스에 작성된 그대로 유지하도록 지시합니다.
    "verbatimModuleSyntax": true,
    
    //컴파일 시 JavaScript 출력 파일을 생성하지 않고, 타입 검사만 수행하도록 합니다.
    "noEmit": true,
    
    //JSON 파일을 모듈로 가져올 수 있도록 허용합니다. 
    "resolveJsonModule": true,
    
    //파일 이름의 대소문자 일관성을 강제합니다.
    "forceConsistentCasingInFileNames" : true
    
    //타입 선언 파일(.d.ts)의 타입 검사를 건너뛰어 컴파일 속도를 향상시킵니다.
    "skipLibCheck": true,
    
    //strict: 모든 엄격한 타입 검사 옵션을 한 번에 활성화합니다.
    //noImplicitAny: 암시적 any 타입을 사용하면 오류를 발생시킵니다.
    //noImplicitThis: this가 암시적으로 any가 되는 경우 오류를 발생시킵니다.
    //alwaysStrict: 모든 파일을 자동으로 strict 모드로 컴파일합니다.
    "strict": true,
    
    //소스맵 파일을 생성하여, 디버깅 시 원본 TypeScript 코드와 매핑할 수 있게 합니다.
    "sourceMap" : true,
    
    //타입 선언 파일(.d.ts)을 생성할지 여부를 지정합니다.
    "declaration" : true,
    
    //이 옵션을 활성화하면, TypeScript 파일(예: .ts나 .tsx)의 파일 확장자를 명시적으로 포함하여 import할 수 있습니다.
    "allowImportingTsExtensions" : true,
    
    //타입 선언 파일(.d.ts)에 대한 소스맵(.d.ts.map)을 생성합니다.
    //라이브러리 배포 시 디버깅이나 IDE 내에서 원본 소스와 타입 선언 간 매핑을 제공하여 개발자 경험을 향상시킵니다.
    "declarationMap" : true,
    
    //증분 컴파일을 활성화하여 이전 컴파일 정보를 저장하고, 변경된 파일만 다시 컴파일하도록 하여 빌드 속도를 향상시킵니다.
    "incremental" : true,
    
    //증분 컴파일(incremental)을 사용할 때, 캐시 정보를 저장할 파일의 경로와 이름을 지정합니다.
    "tsBuildInfoFile" : "node_modules/.tsbuildinfo",
    
    //"auto" (기본값): 파일 내에 import/export 구문이 있으면 모듈로 인식합니다.
    //"force": 모든 파일을 모듈로 취급합니다.
    //"legacy": 이전 방식(암묵적 전역 스크립트 포함)을 사용합니다.
    "moduleDetection" : "force" ,
    
    
    //사용되지 않는 지역 변수(local variable)가 있으면 오류를 발생시킵니다.
    "noUnusedLocals" : 
    
    //사용되지 않는 함수 매개변수(parameter)가 있으면 오류를 발생시킵니다.
    "noUnusedParameters" : 
    
    //switch 문에서 case 구문 사이에 break, return 또는 throw 없이 코드가 넘어가는(fallthrough) 경우 오류를 발생시킵니다.
    "noFallthroughCasesInSwitch" : 
 
  }
}

 

 

 

classic, node, bundler 모듈 해석 방식의 차이점