main-logo

tsconfig.json 속성 알아보기

tsconfig.json의 기본 속성 중 몇가지 옵션에 대해 알아보기

profile
NY
2024년 04월 16일 · 0 분 소요

들어가며

요즘 프로젝트를 진행하면서 Typescript 를 많이 사용하고 있는데 기본 세팅만 사용하다보니 세부 정의 들은 어떤 것들이 있는지 궁금하던 차에 관련해서 강의를 보던 중 tsconfig.json 의 기본적인 옵션들을 알게된 부분이 있어 공유하면 좋겠다고 생각되어 정리해보았습니다. Typescript 관련하여 전반적인 흐름을 알고 싶으시다면 하단의 참고 링크 강의 영상을 참고 부탁 드립니다. (단, 구매가 필요합니다...)

 

tsconfig.json

우선 tsconfig.json 파일의 역할에 대해 알아볼까요?
tsconfig.json 파일은 TypeScript 프로젝트용 구성 파일 중 하나입니다.
해당 파일은 일반적으로 TypeScript 프로젝트의 루트에 배치되고 TypeScript 컴파일러(tsc)가 프로젝트에 대한 다양한 옵션 및 설정을 정의하는 것과 함께 TypeScript 코드를 JavaScript로 변환하는 방법을 지정하는 용도로도 사용할 수 있습니다. tsconfig.json 가 프로젝트 파일 내 존재함으로써 컴파일러에 코드 처리 방법을 안내하고 프로젝트 관리, 빌드 프로세스 및 개발 도구 통합에서 중요한 역할을 한다!라고 생각해주시면 될 것 같습니다.

역할에 대해 조금 더 구체적으로 설명드리자면 아래와 같습니다.

 

핵심 목적

  • 컴파일러 구성: TypeScript 코드를 JavaScript로 컴파일하는 방법을 정의합니다. 여기에는 대상 JavaScript 버전(예: ES5, ES2015), 모듈 해결 전략(예: CommonJS, ES 모듈) 및 기타 컴파일러 동작 지정이 포함됩니다.
  • 프로젝트 구성: 편집 프로세스에 포함할 파일과 제외할 파일을 지정하여 프로젝트를 구성하는 데 도움이 됩니다. 이는 files, include 및 exclude 속성을 사용하여 명시적으로 수행하거나 프로젝트 디렉터리 구조 및 tsconfig.json 설정을 통해 암시적으로 수행할 수 있습니다.
 

주요 특징들

  • 사용자 정의: 프로젝트의 특정 요구 사항에 맞게 컴파일 프로세스를 맞춤화하기 위해 사용자 정의할 수 있는 광범위한 컴파일러 옵션을 제공합니다. 
  • 유형 검사: TypeScript에서 유형 검사의 엄격함을 제어하여 개발 프로세스 초기에 오류를 포착하여 더욱 강력한 코드베이스를 허용합니다.
  • 개발 도구와의 통합: 많은 IDE(통합 개발 환경) 및 코드 편집기는 'tsconfig.json'을 사용하여 코드 완성, 오류 강조, 프로젝트 탐색과 같은 개발 기능을 향상시켜 줍니다.
 

구조 및 옵션

그렇다면 tsconfig.json 파일의 구조와 기본적인 옵션을 살펴볼까요.
아래의 코드는 tsc --init 시 생성되는 기본 설정인데요. 해당 코드를 기준으로 기본적인 사용되는 옵션들을 몇가지 설명드리려고 합니다. (주로 사용되는 아이들로 설명을 드릴 예정이라 몇가지 옵션들은 설명에서 제외되는 점 참고 부탁 드리겠습니다.)

{
	"compilerOptions": {
		/* 기본 옵션 */
		"target": "es5",
		"module": "commonjs",
		"lib": [],
		"allowJs": true,
		"checkJs": false,
		"jsx": "preserve",
		"declaration": true,
		"sourceMap": true,
		"outFile": "./",
		"outDir": "./",
		"rootDir": "./",
		"removeComments": false,
		"noEmit": false, 
		"downlevelIteration": false,
		"noEmitOnError": false,
		  
		/* 엄격한 타입 검사 옵션 */
		"strict": true,
		"noImplicitAny": true,
		"strictNullChecks": true,
		"strictFunctionTypes": true,
		"strictBindCallApply": true,
		"strictPropertyInitialization": true,
		"noImplicitThis": true,
		"alwaysStrict": true,
		
		/* 추가 검사 */
		"noUnusedLocals": false,
		"noUnusedParameters": false,
		"noImplicitReturns": false,
		"noFallthroughCasesInSwitch": false,
	}
}

 

기본 옵션

  • target : 작업 시 어떤 자바스크립트 버전으로 컴파일하고 싶은지를 설정하는 부분입니다. 만약 지정하지 않는다면 Typescript 설치 버전에 따라 기본 값이 다르게 설정됩니다.
    • TypeScript 버전 1.x ~ 2.x: 기본 설정 버전 ES3
    • TypeScript 버전 3.x 이상: 기본 설정 버전 ES5
      • ES5과 ES6버전에 따른 브라우저 호환
      • ES5
        • Internet Explorer 9 이상
        • Firefox 4 이상
        • Chrome 5 이상
        • Safari 5 이상
        • Opera 12 이상
      • ES6
        • Edge 12 이상
        • Firefox 45 이상
        • Chrome 49 이상
        • Safari 10 이상
        • Opera 36 이상
  • module : 프로젝트에 사용할 모듈 시스템을 지정해주는 옵션인데요. 모듈 시스템은 프로젝트 내의 파일 간에 코드 조각(모듈)이 구조화되고, 가져오고, 내보내지는 방식을 정의하는 부분입니다. 이 설정은 TypeScript 파일이 JavaScript로 컴파일되는 방식을 결정하고 다양한 환경(예: 브라우저, Node.js 또는 Webpack 또는 Rollup과 같은 번들러)에서 로드 및 실행되는 방식에 영향을 미치기 때문에 중요하다고 합니다.
    • 옵션의 종류 : none / commonjs / amd / system / umd / es2015 / es2020 or ESNext
  • lib : 타입스크립트의 객체 및 기능 기본 값을 지정할 수 있는 옵션입니다. DOM 으로 작업하는 경우 설정하지 않으면 기본 값을 사용하게 되는데 기본 값은 target 설정에 따라 달라집니다. es6로 설정한 경우 전역으로 사용할 수 있는 모든 기능이 기본으로 포함되어 있습니다. 굳이 map 객체를 타입스크립트로 따로 정의하지 않아도 해당 객체를 사용할 수 있습니다. (에러가 안난단 이야기...) 기본적으로 주석 처리된 상태로 제공되는 경우가 있는데 해당 옵션을 주석을 해제하면 더 이상 기본 값을 사용하지 않기 때문에 해당 DOM 을 사용할 수 있도록 관련된 라이브러리들을 포함시켜주지 않으면 에러가 발생하게 됩니다. 예를 들어 document, console 같은 기본적인 것들을 설정해주어야 사용할 수 있게 됩니다. tsconfig를 잘 파악하여 관련 설정을 꼼꼼히 해줄 수 없다면 되도록이면 주석을 풀지 않는 것을 추천드립니다. 주석을 푸는 경우 자동완성으로 dom 등을 추가하여 설정하면 된다고 하지만요... 관련하여 자세한 정보는 글 하단에 링크해둔 공식 문서를 확인하시면 제공되는 많은 옵션을 확인하실 수 있습니다.
  • allowJs : 컴파일에 자바스크립트를 포함시킬 수 있습니다. 즉, .ts 파일이 아니더라도 (자바스크립트 파일도 포함하여) 컴파일을 진행합니다.
  • checkJs : 컴파일 하진 않지만 구문을 검사하고 잠재적 오류를 보고 해줍니다. 주로 사용하는 경우는 타입스크립트를 사용하고 싶진 않지만 타입스크립트의 기능을 활용하고 싶은 경우. 해당 옵션을 활성화하면 타입스크립트의 경우는 any 타입에 대해서만 도움을 줄 수 있습니다.
    • allowJs, checkJs 옵션들은 타입스크립트로부터 파생된 자바스크립트 파일을 이중으로 컴파일하지 않도록 하려면 exclude나 include 설정을 약간 조정해주어야 합니다.
    • 타입스크립트를 전혀 사용하고 싶지 않은 플젝이나, 어떤 이유로든 타입스크립트 옆에 자바스크립트 파일이 있는 경우라면 자바스크립트 파일을 확인할 때 사용합니다.
  • jsx : .tsx 파일에서 JSX 구문을 JavaScript로 제대로 컴파일하는지 확인이 필요한 경우 사용합니다.
  • sourceMap : 디버깅과 개발에 도움을 주는 옵션인데요. 활성화 시 '.map' 파일을 생성합니다.
    • 개발자도구에 Sourses 탭에서 자바스크립트 파일을 확인할 수 있는데 컴파일된 자바스크립트 코드가 아닌 타입스크립트 코드를 디버깅하고 싶을 때 해당 옵션을 사용합니다. 옵션 값을 true 로 설정하고 tsc 명령을 다시 실행하면 .js.map 파일이 만들어지는데 해당 파일은 모던 브라우저와 개발자 도구에서 자바스크립트 파일을 입력 파일에 연결하는 다리 역할을 해줍니다. 그렇게 해서 생성된 파일을 다시 로드하면 Sourses 탭에서 자바스크립트 파일 뿐 아니라, 타입스크립트 파일도 볼 수 있게 됩니다. 중단 점을 설정하여 디버깅도 할 수 있습니다.
  • outFile : 출력을 단일 파일로 연결하고 내보냅니다.
  • outDir : 출력 구조를 디렉토리로 리디렉션합니다.
    • 해당 옵션을 설정하면 ts 컴파일러에게 생성된 파일을 어디에 저장해야하는지 알려줍니다. ts 파일이 있는 폴더 구조 그대로 컴파일하기 때문에 작업 시 편리하게 사용할 것 같습니다.
  • rootDir : 입력 파일의 루트 디렉토리를 지정합니다. --outDir과 함께 사용하여 출력 디렉토리 구조를 제어합니다.
    • 해당 옵션을 src 로 설정하면 ts 파일이 있는 폴더가 root 레벨에 있더라도 출력에 포함되지 않습니다.
  • removeComments : 출력에서 주석을 제거하지 않는 옵션인데요. ts 파일 내 모든 주석을 제거하고 컴파일된 자바스크립트 파일만 남게되어 파일 용량을 줄일 수가 있습니다.
  • noEmit : 자바스크립트 파일을 생성하지 않고 확인만 하고 싶은 경우 사용합니다. 시간 절약을 위해 컴파일러가 파일만 검사하고 잠재적 오류를 보고하되 파일을 만들지는 않게 해주는 옵션입니다.
  • downlevelIteration : for 루프를 사용하는 경우 드물게 컴파일이 제대로 안되는 문제가 있는데 그런 경우 해당 옵션을 true 로 설정해주면 더 정확히 컴파일을 하게 됩니다. 다만, 항상 해당 옵션을 켠 경우 많은 양의 코드가 출력될 수 있으므로 루프가 있고 생성된 코드에서 루프가 예상과 다른 방식으로 동작 시 켜는게 좋습니다.
  • noEmitOnError : 기본 설정에 포함되어있지 않은 옵션인데요. 기본 값은 false이며, true 로 설정하면 타입스크립트 상에 오류가 발생한 경우 해당 파일은 자바스크립트로 컴파일하지 않습니다.
 

엄격한 타입 검사 옵션

  • strict : 모든 엄격한 타입 검사 옵션을 활성화합니다.
    • true 설정 시 모든 strict 타입 검사 옵션이 활성화됩니다. 즉, 모든 옵션을 개별적으로 하나씩 설정하거나 이 옵션만 설정하면 됩니다. 다만, 어떤 옵션을 false 로 설정하려는 경우 각 옵션을 개별적으로 설정해줘야 합니다. 그렇지 않으면 모두 true 로 설정됩니다.
  • noImplicitAny : 암시된 'any' 타입에 대한 표현식과 선언에 오류를 발생시켜 매개변수, 코드에서 작업 중인 값에 대해 명확히 해줄 수 있는 옵션입니다. 예를 들어 매개변수로 가져올 인자 값의 타입이 타입스크립트로 선언되어있지 않아 유추할 수 없는 상황이라면 오류를 뱉어내게 됩니다.
  • strictNullChecks : 엄격한 null 검사를 활성화합니다.
    • 해당 옵션은 DOM과 같은 선택된 노드에 대한 관련이 있는 옵션인데요. 타입스크립트에게 엄격하게 하라고 하는 옵션입니다. 잠재적으로 null이 될 수 있는 값에 접근하고 작업 시 undefined 나 null을 반환 시 코드 실행이 실패할 수 있기 때문에 그런 오류들을 방지하기 위해 미리 체크해줍니다. 예시로 정의를 찾지못해 null 에러가 뜨는 경우 !를 사용하여 null 이 아닌 값이 반환된다고 선언하여 해결할 수도 있습니다. 만약 !를 사용하지않고 해당 DOM이 있을 때만 실행하도록 if문으로 해당 구문을 감싸서 체크한다면 에러를 뱉지않도록 보완된 코드를 작성할 수 있을 것 입니다.
  • strictFunctionTypes : 함수 타입의 엄격한 검사를 활성화합니다.
    • 매개변수와 반환 값과 관련해서 함수가 어떻게 생겼는지 정의하고 함수 타입을 만듭니다.
  • strictBindCallApply : 함수의 엄격한 'bind', 'call', 및 'apply' 메소드를 활성화합니다.
    • bind(), call(), apply() 작업을 하는 경우 유용하게 사용할 수 있는 옵션인데요. 넘기는 인수가 잘못된 경우 에러를 뱉어내되어 설정한 값이 맞는지 체크할 수 있습니다.
  • strictPropertyInitialization : 클래스 속성이 생성자에서 초기화되었는지 확인합니다.
    • 클래스 타입으로 작업 시 중요하게 사용된다고 합니다.
  • noImplicitThis : 암시적 'any' 타입을 가진 'this' 표현에 오류를 발생시킵니다.
    • this 키워드와 연결되어 무엇을 참조하는지 분명하지 않은 곳에서 this를 사용하면 에러를 뱉어내줍니다.
  • alwaysStrict : 각 소스 파일에 대해 엄격 모드를 구문 분석하고 "use strict"를 내보냅니다.
    • 생성되는 자바스크립트 파일이 strict 모드를 사용하도록 합니다.
 

추가 검사

  • noUnusedLocals : 사용되지 않는 지역변수에 대한 오류를 보고합니다.
  • noUnusedParameters : 사용되지 않는 매개변수에 대한 오류를 보고합니다.
  • noImplicitReturns : 함수에서 모든 코드 경로가 값을 반환하지 않으면 오류를 보고합니다.
  • noFallthroughCasesInSwitch : switch 문에서 fallthrough 케이스에 대한 오류를 보고합니다.

 

기본 설정 외 추가로 많이 사용하는 옵션

많지 않은 부분이어서 코드 내 주석으로 설명을 추가하였습니다.

{
	"exclude": [
		// 해당 영역에는 컴파일에 포함하지 않아야하는 파일들을 설정합니다.
		"folder_name", // 폴더명
		"node_modules", // node_module 은 굳이 설정하지 않아도 기본적으로 컴파일 하지 않음. 폴더명 예시로만 참고.
		"file.ts", // 파일명
		"**/*.ts" // 와일드카드를 사용하여 모든 폴더 또는 모든 파일을 한번에 설정할 수도 있습니다.
	],
	"include": [
		// 해당 영역에는 컴파일을 해야하는 파일들을 설정합니다.
		// 다만 여기에 없는 파일들은 컴파일되지 않기 때문에 일일히 다 설정해줘야하는 번거로움이 발생할 수 있어 include 는 거의 설정하지 않습니다.
		"file.ts" 
	]
}

 

마치며

Typescript 프로젝트를 진행하면서 기본 프로젝트 세팅 상태 그대로만 사용했었는데 옵션에 대한 이해를 갖고 컴파일러 관련해서 확인 후 프로젝트 규모에 따라서 옵션 활성화 및 설정 등을 추가적으로 확인해보면서 활용도를 높일 수 있다면 조금 더 안정성있는 작업을 할 수 있지 않을까 하여 정리 및 공유를 드려보았습니다.
해당 내용 정리는 여기까지이며, 업무를 진행함에 있어 작게나마 도움이 되셨다면 좋겠습니다.
이후 내용이 추가나 수정이 필요한 부분이 있다면 언제든 알려주세요.
부족한 글 읽어주셔서 감사합니다. 🙇🏻‍♀️
그럼 안녕히…👋 -The End-

 

참고문서