TypeScript

[TypeScript] 파일 생성 방법(Target, Lib, Declaration file, JsDoc)

winter17 2023. 8. 10. 12:28

⚠️ create-react-app, next.js, nest.js 같은 프레임워크를 쓴다면 아래와 같은 과정이 필요 없지만 알아둘 것

 

1. 타입스크립트 프로젝트를 위한 폴더를 생성 후 vs code에서 오픈

mkdir 폴더명

 

2. 터미널에서 명령어 입력: npm init -y

// package.json
// 명령어 입력시 아래와 같은 코드가 생성됨
// 기본 코드에서 main 제거, script를 수정한 상태
{
  "name": "typechain",
  "version": "1.0.0",
  "description": "",
  "scripts": {
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

 

3. 터미널에서 명령어 입력: npm i -D typescript

// package.json
{
  "name": "typechain",
  "version": "1.0.0",
  "description": "",
  "scripts": {},
  "keywords": [],
  "author": "",
  "license": "ISC",
  // 이 부분이 자동 생성
  "devDependencies": {
    "typescript": "^5.1.6"
  }
}

 

4. src 폴더 생성 후 index.ts 파일 생성

임시 코드 생성

 

5. 명령어를 통해 tsconfig.json파일 생성: touch tsconfig.json

  • tsconfid.json: vs code는 우리가 타입스크립트로 작업한다는 것을 즉시 알게 되고 자동완성기능을 제공함
// tsconfig.json
{
  // include 배열에는 자바스크립트로 컴파일하고 싶은 모든 디렉터리
  "include": [
    // 타입스크립트가 src의 모든 파일을 확인한다
    "src"
  ],
  "compilerOptions": {
    // outDir은 자바스크립트 파일이 생성될 디렉터리를 지정
    "outDir": "build"
  }
}

 

6. package.json 파일에서 scripts 부분 채우기

// package.json
"scripts": {
    //  아래 코드를 작성하여 tsc를 작동시킬 수 있도록 준비
    //  저장 후 npm run build 명령어로 활성화 -> build폴더와 Index.js파일 생성
    "build": "tsc"
},

 

7. npm run build 명령어로 tsc를 활성화하여 build폴더와 index.js파일 생성

index.ts 파일의 타입스크립트 코드를 자바스크립트로 자동 컴파일

 

8. tsconfig.json에서 target 추가

{
  // include 배열에는 자바스크립트로 컴파일하고 싶은 모든 디렉터리
  "include": [
    // 타입스크립트가 src의 모든 파일을 확인한다
    "src"
  ],
  "compilerOptions": {
    // outDir은 자바스크립트 파일이 생성될 디렉터리를 지정
    "outDir": "build",
    // target은 어떤 버전의 자바스크립트로 타입스크립트를 컴파일하고 싶은지 나타냄
    // ES3는 const, var가 존재 하지 않음
    "target": "ES3" // -> npm run build
  }
}

 

9. 타입스크립트 코드가 자바스크립트 코드가 어떻게 변화하는지 확인

// index.ts
class Block{
  constructor{
    private data: string{
      static hello(){
        return 'hi'
      }
    }
  }
}

위의 코드 작성 후 num run build

// index.js
// ES3버전의 자바스크립트 코드로 자동 변환
var Block = /** @class */ (function () {
    function Block() {
    }
    return Block;
}());
constructor;
{
    data: string;
    {
        hello();
        {
            return 'hi';
        }
    }
}

 

10. ES6 버전으로 변경하여 최신 상태의 버전으로 바꿔주고 확인

// tsconfig.json
"target": "ES6"

npm run build

// index.js
// index.ts에서 작성한 타입스크립트 코드가 ES6버전의 자바스크립트 코드로 변환
class Block {
}
constructor;
{
    data: string;
    {
        hello();
        {
            return 'hi';
        }
    }
}

 

11. tsconfig.json 파일에 lib 속성 추가

// tsconfig.json
{
  "include": ["src"],
  "compilerOptions": {
    "outDir": "build",
    "target": "ES6",
    // lib은 합쳐진 라이브러리의 '정의 파일'을 특정해주는 역할
    // 정의 파일은 자바스크립트 코드가 어디에서 동작할지 알려줌(자바스크립트의 어떤 버전이 그 환경에서 사용되는지)
    "lib": ["ES6", "DOM"] // ES6를 지원하는 서버와, DOM(브라우저 환경에서 코드를 실행시킴)
  }
}

 

▶ 정의 파일 Declaration Files

Declaration Files

// tsconfig.ts
{
  "include": ["src"],
  "compilerOptions": {
    "outDir": "build",
    // Common JS 모듈과 ES6 모듈 간의 호환성을 활성화
    // import문과 require문을 혼용하여 사용할 수 있음
    "esModuleInterop": true,
    "target": "ES6",
    "lib": ["ES6", "DOM"],
    // 엄격한 타입 검사를 활성화 -> 타입스크립트의 타입 체크 규칙이 적용됨
    "strict": true,
    // 자바스크립트 파일을 컴파일할 수 있도록 허용. 타입스크립트 컴파일러는 자바스크립트 파일에 대해서도 타입 검사를 수행할
    "allowJs": true
  }
}

 

타입스크립트가 localStorage, Math, window 등의 타입을 이해하고 인지하고 있는데, 어떻게 타입스크립트가 그것들을 알고 있을까?

타입스크립트는 자바스크립트의 기능을 기본적으로 포함하고 있으며, 자바스크립트의 내장 객체 및 API를 타입으로 정의하여 제공한다. 이를 통해 타입스크립트는 다양한 내장 객체와 API를 이해하고 활용할 수 있다

 

타입스크립트는 자체적으로 내장 객체 및 API의 타입 정의 파일을 포함하고 있다. 이 타입 정의 파일은 '. d.ts' 확장자를 가진 파일들로서, 자바스크립트 런타임 환경에서 제공되는 객체와 함수들의 타입 정보를 포함하고 있다. 이를 통해 타입스크립트는 코드 작성 중에 내장 객체와 API의 타입 정보를 활용하여 코드를 분석하고 타입 검사를 수행한다. 

 

예를 들어, 'localStorage', 'Math', 'window'와 같은 객체의 타입 정보는 타입스크립트의 내장 타입 정의 파일을 통해 제공된다. 이 파일들에는 해당 객체의 속성, 메서드, 반환 타입 등이 정의되어 있어 타입스크립트가 코드를 분석할 때 이 정보를 활용하여 타입을 추론하고 검사한다. 

 

lib: https://www.typescriptlang.org/tsconfig#lib

nomadcoder[declaration_files]: https://nomadcoders.co/typescript-for-beginners/lectures/3687

 

 

12. JSDoc

  • 자바스크립트 코드에 문서화 주석을 추가하여 코드의 설명, 타입 정보, 매개변수, 반환값 등을 문서화하는 데 사용되는 주석 스타일.
  • JSDoc 주석은 주로 개발자들 사이에서 코드의 의도와 사용 방법을 명확하게 전달하고 코드를 문서화하는 데 사용된다.
  • 타입 스크립트의 타입 체크 및 자동 완성도에 활용된다. 
/**
 * This is a JSDoc comment.
 *
 * @param {string} param1 - Description of the first parameter.
 * @param {number} param2 - Description of the second parameter.
 * @returns {boolean} Description of the return value.
 */
function myFunction(param1, param2) {
  // ...
  return true;
}

JSDoc 주석의 주요 요소와 사용법:

  1. /** ... */: JSDoc 주석은 /**로 시작하고 */로 끝난다.
  2. @param: 함수의 매개변수에 대한 설명을 추가할 때 사용된다. 매개변수의 이름과 타입, 그리고 설명을 지정할 수 있다.
  3. @returns 또는 @return: 함수의 반환값에 대한 설명을 추가할 때 사용된다.
  4. @type: 변수 또는 속성의 타입을 명시할 때 사용된다.
  5. @description: 해당 주석 블록에 대한 설명을 추가할 때 사용된다.
  6. @example: 코드의 사용 예제를 추가할 때 사용된다.
  7. @see: 다른 관련 문서나 리소스를 참조할 때 사용된다.

JSDoc 주석을 사용하면 IDE나 문서 생성 도구 등에서 코드의 문서화를 보다 쉽게 할 수 있다. 또한 타입 정보를 포함하여 코드의 타입 체크를 강화하거나 자동 완성 기능을 개선하는 데도 활용될 수 있다.

주의할 점은 JSDoc 주석은 주석으로 작성되기 때문에 코드의 실행에 영향을 미치지 않는다. 따라서 올바른 주석을 작성하고 관리하는 것이 중요하다. 코드를 문서화하면 코드의 가독성과 유지 보수성을 향상할 수 있다.