2025년 7월 21일한국어

이 심층적인 tsconfig.json 가이드로 TypeScript 설정을 마스터하세요. 효율적인 개발을 위한 필수 컴파일러 옵션, 프로젝트 설정 및 고급 구성을 배우세요.

TypeScript 설정: 종합 tsconfig.json 가이드

JavaScript의 상위 집합인 TypeScript는 동적인 웹 개발 세계에 정적 타이핑을 도입합니다. 잘 구성된 tsconfig.json 파일은 TypeScript의 모든 기능을 활용하는 데 매우 중요합니다. 이 가이드는 tsconfig.json에 대한 포괄적인 개요를 제공하며, 필수 컴파일러 옵션, 프로젝트 설정 및 고급 구성을 다룹니다.

tsconfig.json이란 무엇인가요?

tsconfig.json 파일은 TypeScript 프로젝트의 컴파일러 옵션을 지정하는 설정 파일입니다. 이 파일은 TypeScript 컴파일러에게 TypeScript 코드를 JavaScript로 변환하는 방법을 알려줍니다. 이 파일은 프로젝트의 구조를 정의하고, 컴파일 규칙을 설정하며, 팀이 단일 사무실에 있든 여러 대륙에 분산되어 있든 관계없이 개발 팀 전체의 일관성을 보장하는 데 필수적입니다.

tsconfig.json 파일 생성하기

tsconfig.json 파일을 생성하려면 터미널에서 프로젝트의 루트 디렉터리로 이동하여 다음 명령을 실행하세요:

            tsc --init

이 명령은 일반적으로 사용되는 컴파일러 옵션이 포함된 기본 tsconfig.json 파일을 생성합니다. 그런 다음 프로젝트의 특정 요구 사항에 맞게 파일을 사용자 정의할 수 있습니다. 일반적인 tsconfig.json에는 compilerOptions, include, exclude와 같은 옵션이 포함됩니다.

필수 컴파일러 옵션

compilerOptions 섹션은 tsconfig.json 파일의 핵심입니다. 여기에는 TypeScript 컴파일러의 동작을 제어하는 다양한 옵션이 포함되어 있습니다. 다음은 가장 중요한 컴파일러 옵션 중 일부입니다:

`target`

target 옵션은 생성될 JavaScript 코드의 ECMAScript 대상 버전을 지정합니다. 일반적인 값으로는 ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext가 있습니다. 올바른 대상을 선택하는 것은 브라우저나 Node.js 버전과 같은 의도된 런타임 환경과의 호환성을 보장하는 데 중요합니다.

예시:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}

`module`

module 옵션은 모듈 코드 생성 스타일을 지정합니다. 일반적인 값으로는 CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020, ESNext가 있습니다. 모듈 시스템의 선택은 대상 환경과 사용되는 모듈 번들러(예: Webpack, Rollup, Parcel)에 따라 달라집니다. Node.js의 경우 CommonJS가 자주 사용되는 반면, 최신 웹 애플리케이션의 경우 모듈 번들러와 함께 ES6 또는 ESNext가 선호됩니다. ESNext를 사용하면 개발자는 최신 기능과 최적화를 활용하면서 최종 모듈 형식은 번들러가 처리하도록 할 수 있습니다.

예시:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}

`lib`

lib 옵션은 컴파일에 포함될 라이브러리 파일 목록을 지정합니다. 이 라이브러리 파일들은 내장 JavaScript API 및 브라우저 API에 대한 타입 정의를 제공합니다. 일반적인 값으로는 ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String 등이 있습니다. 적절한 라이브러리를 선택하면 TypeScript 컴파일러가 대상 환경에 필요한 타입 정보를 갖도록 보장합니다. DOM 라이브러리를 사용하면 프로젝트가 타입 오류 없이 브라우저 특정 API를 사용하는 코드를 컴파일할 수 있습니다.

예시:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}

`allowJs`

allowJs 옵션은 TypeScript 컴파일러가 TypeScript 파일과 함께 JavaScript 파일을 컴파일하도록 허용합니다. 이는 기존 JavaScript 프로젝트를 점진적으로 TypeScript로 마이그레이션할 때 유용합니다. 이 값을 true로 설정하면 컴파일러가 .js 파일을 처리할 수 있게 되어 프로젝트 내에서 점진적인 TypeScript 채택이 가능해집니다.

예시:

            {
  "compilerOptions": {
    "allowJs": true
  }
}

`jsx`

jsx 옵션은 JSX 구문을 처리하는 방법을 지정합니다. 일반적인 값으로는 preserve, react, react-native, react-jsx가 있습니다. preserve는 출력에서 JSX 구문을 유지하는 반면, react는 JSX를 React.createElement 호출로 변환합니다. react-jsx는 React 17에 도입된 새로운 JSX 변환을 사용하며, 이는 React를 가져올 필요가 없습니다. 올바른 JSX 옵션을 선택하는 것은 React 또는 다른 JSX 기반 라이브러리를 사용하는 프로젝트에 매우 중요합니다.

예시:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

`declaration`

declaration 옵션은 각 TypeScript 파일에 해당하는 .d.ts 선언 파일을 생성합니다. 선언 파일에는 타입 정보가 포함되어 있으며, 컴파일된 코드를 사용하는 다른 TypeScript 프로젝트에서 사용됩니다. 선언 파일을 생성하는 것은 재사용 가능한 라이브러리 및 모듈을 만드는 데 필수적입니다. 이 파일들을 통해 다른 TypeScript 프로젝트는 원본 소스 코드를 컴파일할 필요 없이 라이브러리가 노출하는 타입과 인터페이스를 이해할 수 있습니다.

예시:

            {
  "compilerOptions": {
    "declaration": true
  }
}

`sourceMap`

sourceMap 옵션은 생성된 JavaScript 코드를 원본 TypeScript 코드로 다시 매핑하는 소스 맵 파일을 생성합니다. 소스 맵은 브라우저 및 기타 환경에서 TypeScript 코드를 디버깅하는 데 필수적입니다. JavaScript 코드에서 오류가 발생하면 소스 맵을 통해 개발자는 디버거에서 해당 TypeScript 코드를 볼 수 있어 문제를 더 쉽게 식별하고 수정할 수 있습니다.

예시:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}

`outDir`

outDir 옵션은 생성된 JavaScript 파일의 출력 디렉터리를 지정합니다. 이 옵션은 소스 코드와 컴파일된 코드를 분리하여 프로젝트의 빌드 출력을 구성하는 데 도움이 됩니다. outDir을 사용하면 빌드 프로세스를 더 쉽게 관리하고 애플리케이션을 배포할 수 있습니다.

예시:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}

`rootDir`

rootDir 옵션은 TypeScript 프로젝트의 루트 디렉터리를 지정합니다. 컴파일러는 이 디렉터리를 모듈 이름을 확인하는 기준으로 사용합니다. 이 옵션은 복잡한 디렉터리 구조를 가진 프로젝트에 특히 중요합니다. rootDir을 올바르게 설정하면 컴파일러가 필요한 모든 모듈과 종속성을 찾을 수 있습니다.

예시:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}

`strict`

strict 옵션은 모든 엄격한 타입 검사 옵션을 활성화합니다. 이는 개발 과정 초기에 잠재적인 오류를 포착하는 데 도움이 되므로 새로운 TypeScript 프로젝트에 강력히 권장됩니다. 엄격 모드를 활성화하면 더 엄격한 타입 검사 규칙이 적용되어 더 견고하고 유지보수하기 쉬운 코드를 작성할 수 있습니다. 모든 새로운 TypeScript 프로젝트에서 엄격 모드를 활성화하는 것이 모범 사례입니다.

예시:

            {
  "compilerOptions": {
    "strict": true
  }
}

`esModuleInterop`

esModuleInterop 옵션은 CommonJS와 ES 모듈 간의 상호 운용성을 활성화합니다. 이는 두 가지 유형의 모듈을 모두 사용하는 프로젝트에 중요합니다. esModuleInterop이 활성화되면 TypeScript는 CommonJS와 ES 모듈 간의 차이점을 자동으로 처리하여 두 시스템 간에 모듈을 더 쉽게 가져오고 내보낼 수 있도록 합니다. 이 옵션은 다른 모듈 시스템을 사용할 수 있는 타사 라이브러리와 작업할 때 특히 유용합니다.

예시:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}

`moduleResolution`

moduleResolution 옵션은 TypeScript가 모듈 가져오기를 확인하는 방법을 지정합니다. 일반적인 값으로는 Node와 Classic이 있습니다. Node 모듈 확인 전략이 기본값이며 Node.js 모듈 확인 알고리즘을 기반으로 합니다. Classic 모듈 확인 전략은 더 오래되었고 덜 일반적으로 사용됩니다. Node 모듈 확인 전략을 사용하면 TypeScript가 Node.js 환경에서 모듈 가져오기를 올바르게 확인할 수 있습니다.

예시:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}

`baseUrl` and `paths`

baseUrl과 paths 옵션은 상대적이지 않은 모듈 가져오기에 대한 모듈 확인을 구성하는 데 사용됩니다. baseUrl 옵션은 상대적이지 않은 모듈 이름을 확인하기 위한 기본 디렉터리를 지정합니다. paths 옵션을 사용하면 모듈 이름을 파일 시스템의 특정 위치에 매핑할 수 있습니다. 이러한 옵션은 복잡한 디렉터리 구조를 가진 프로젝트와 모듈 가져오기를 단순화하는 데 특히 유용합니다. baseUrl과 paths를 사용하면 코드를 더 읽기 쉽고 유지보수하기 쉽게 만들 수 있습니다.

예시:

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

Include 및 Exclude 옵션

include와 exclude 옵션은 컴파일에 포함할 파일과 제외할 파일을 지정합니다. 이러한 옵션은 파일 이름을 일치시키기 위해 glob 패턴을 사용합니다. include와 exclude를 사용하면 TypeScript 컴파일러가 처리할 파일을 제어하여 빌드 성능을 개선하고 오류를 줄일 수 있습니다. 컴파일에 포함할 파일을 명시적으로 지정하는 것이 모범 사례입니다.

예시:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Extends 옵션

extends 옵션을 사용하면 다른 tsconfig.json 파일에서 컴파일러 옵션을 상속받을 수 있습니다. 이는 여러 프로젝트 간에 공통 구성 설정을 공유하거나 기본 구성을 만드는 데 유용합니다. extends 옵션을 사용하면 코드 재사용을 촉진하고 중복을 줄일 수 있습니다. 기본 구성을 만들고 개별 프로젝트에서 확장하는 것이 모범 사례입니다.

예시:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}

고급 구성

필수 컴파일러 옵션 외에도 tsconfig.json은 특수한 시나리오를 위한 고급 구성을 지원합니다.

증분 컴파일

대규모 프로젝트의 경우 증분 컴파일은 빌드 시간을 크게 향상시킬 수 있습니다. TypeScript는 이전 컴파일 결과를 캐시하고 변경된 파일만 다시 컴파일할 수 있습니다. 증분 컴파일을 활성화하면 대규모 프로젝트의 빌드 시간을 획기적으로 줄일 수 있습니다. 이는 많은 수의 파일과 종속성을 가진 프로젝트에 특히 중요합니다.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

프로젝트 참조

프로젝트 참조를 사용하면 대규모 TypeScript 프로젝트를 더 작고 독립적인 모듈로 구조화할 수 있습니다. 이는 빌드 시간과 코드 구성을 개선할 수 있습니다. 프로젝트 참조를 사용하면 대규모 프로젝트를 더 관리하기 쉽고 유지보수하기 쉽게 만들 수 있습니다. 크고 복잡한 프로젝트에는 프로젝트 참조를 사용하는 것이 모범 사례입니다.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}

사용자 지정 타입 정의

때로는 타입 정의가 없는 JavaScript 라이브러리에 대한 타입 정의를 제공해야 할 수도 있습니다. 사용자 지정 .d.ts 파일을 만들어 이러한 라이브러리의 타입을 정의할 수 있습니다. 사용자 지정 타입 정의를 생성하면 타입 안전성을 희생하지 않고도 TypeScript 코드에서 JavaScript 라이브러리를 사용할 수 있습니다. 이는 레거시 JavaScript 코드나 자체 타입 정의를 제공하지 않는 라이브러리와 작업할 때 특히 유용합니다.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}

모범 사례

엄격 모드 사용: 향상된 타입 검사를 위해 strict 옵션을 활성화하세요.
대상 지정: 런타임 환경에 적합한 target 버전을 선택하세요.
출력 구성: outDir을 사용하여 소스 코드와 컴파일된 코드를 분리하세요.
종속성 관리: include 및 exclude를 사용하여 컴파일할 파일을 제어하세요.
Extends 활용: extends 옵션으로 공통 구성 설정을 공유하세요.
버전 관리에 설정 파일 포함: 개발 환경과 CI/CD 파이프라인 전반에 걸쳐 일관성을 유지하기 위해 `tsconfig.json`을 git에 커밋하세요.

일반적인 문제 해결

tsconfig.json을 구성하는 것은 때때로 어려울 수 있습니다. 다음은 몇 가지 일반적인 문제와 해결 방법입니다:

모듈 확인 문제

모듈 확인 오류가 발생하면 moduleResolution 옵션이 올바르게 구성되었는지, baseUrl 및 paths 옵션이 제대로 설정되었는지 확인하세요. paths 옵션에 지정된 경로가 올바른지 다시 확인하세요. 필요한 모든 모듈이 node_modules 디렉터리에 설치되었는지 확인하세요.

타입 오류

타입 정의가 부정확하거나 누락된 경우 타입 오류가 발생할 수 있습니다. 사용 중인 모든 라이브러리에 대해 올바른 타입 정의가 설치되어 있는지 확인하세요. 타입 정의가 없는 JavaScript 라이브러리를 사용하는 경우 사용자 지정 타입 정의를 만드는 것을 고려하세요.

컴파일 오류

TypeScript 코드에 구문 오류나 타입 오류가 있는 경우 컴파일 오류가 발생할 수 있습니다. 오류 메시지를 주의 깊게 검토하고 구문 오류나 타입 오류를 수정하세요. 코드가 TypeScript 코딩 규칙을 따르는지 확인하세요.

결론

잘 구성된 tsconfig.json 파일은 성공적인 TypeScript 프로젝트에 필수적입니다. 필수 컴파일러 옵션과 고급 구성을 이해함으로써 개발 워크플로를 최적화하고, 코드 품질을 향상시키며, 대상 환경과의 호환성을 보장할 수 있습니다. tsconfig.json을 올바르게 구성하는 데 시간을 투자하면 오류를 줄이고, 유지보수성을 향상시키며, 빌드 프로세스를 간소화하여 장기적으로 이익이 될 것입니다. 이는 더 효율적이고 신뢰할 수 있는 소프트웨어 개발로 이어집니다. 여기에 제공된 정보는 보편적으로 적용 가능하도록 설계되었으며, TypeScript로 새로운 프로젝트를 시작하기 위한 견고한 기반을 제공해야 합니다.

모든 사용 가능한 컴파일러 옵션에 대한 최신 정보와 자세한 설명을 보려면 공식 TypeScript 문서를 참조하는 것을 잊지 마세요. TypeScript 문서는 TypeScript 구성의 복잡성을 이해하는 데 귀중한 자료입니다.