TypeScript

TypeScript는 일반 JavaScript로 컴파일되고 타입이 있는 상위 집합입니다. 이 가이드에서는 TypeScript를 webpack과 통합하는 방법에 대해 알아보겠습니다.

Basic Setup

먼저 다음을 실행하여 TypeScript 컴파일러와 로더를 설치하세요.

npm install --save-dev typescript ts-loader

이제 디렉터리 구조와 설정 파일을 수정합니다.

project

 webpack-demo
  ├── package.json
  ├── package-lock.json
+ ├── tsconfig.json
- ├── webpack.config.js
+ ├── webpack.config.ts
  ├── /dist
  │   ├── bundle.js
  │   └── index.html
  ├── /src
- │   ├── index.js
+ │   └── index.ts
  └── /node_modules

tsconfig.json

JSX를 지원하도록 간단하게 설정하고 TypeScript를 ES5로 컴파일 합니다.

{
  "compilerOptions": {
    "outDir": "./dist/",
    "noImplicitAny": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "target": "esnext",
    "jsx": "react-jsx",
    "allowJs": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

tsconfig.json 설정 옵션에 대한 자세한 내용은 TypeScript 문서를 참고하세요.

webpack 설정에 대한 자세한 내용은 설정 콘셉트를 참고하세요.

이제 TypeScript를 처리하도록 webpack을 설정해 보겠습니다.

먼저 필요한 종속성을 설치하세요.

npm install --save-dev ts-node @types/node

webpack.config.ts

import path from "node:path";
import { fileURLToPath } from "url";
import webpack from "webpack";

// `devServer`를 구성하는 동안 TypeScript 오류가 발생하는 경우
import "webpack-dev-server";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const config: webpack.Configuration = {
  entry: "./src/index.ts",
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: "ts-loader",
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: [".tsx", ".ts", ".js"],
  },
  output: {
    filename: "bundle.js",
    path: path.resolve(__dirname, "dist"),
  },
};

export default config;

TypeScript 파일에 설정을 작성하는 방법에 대한 자세한 내용은 다음 링크를 참조하세요. (https://webpack.js.org/configuration/configuration-languages/#typescript)

이렇게하면 webpack이 ./index.ts 를 통해 진입하고, ts-loader를 통해 모든 .ts.tsx 파일을 로드합니다. 그리고 현재 디렉터리에 bundle.js파일을 출력합니다.

다음으로, ./index.ts에서 lodash를 가져오는 방식을 수정해야 합니다. lodash 정의에는 기본 export가 포함되어 있지 않으므로 import 문을 업데이트해야 합니다. 먼저 TypeScript 정의를 설치했는지 확인하세요.

npm install --save-dev @types/lodash

그런 다음 파일 맨 위에 있는 import 내용을 업데이트하세요.

./index.ts

- import _ from 'lodash';
+ import * as _ from 'lodash';

  function component() {
    const element = document.createElement('div');

    element.innerHTML = _.join(['Hello', 'webpack'], ' ');

    return element;
  }

  document.body.appendChild(component());

Ways to Use TypeScript in webpack.config.ts

webpack.config.ts에서 TypeScript를 사용하는 방법은 세 가지입니다.

  1. Node.js의 내장 타입 제거 기능을 사용하는 webpack (권장)

    webpack -c ./webpack.config.ts

    Node.js의 내장 타입 제거를 사용하여 구성을 로드하려고 시도한 다음, interpretrechoir를 사용하여 구성 파일을 로드하려고 시도합니다(이 경우 tsx 또는 ts-node 또는 기타 도구를 설치해야 합니다).

  2. Node.js에서 사용자 지정 --import/--require 사용:

    NODE_OPTIONS='--import=tsx --no-experimental-strip-types'  webpack -c ./webpack.config.ts
    NODE_OPTIONS='--require=ts-node/register --no-experimental-strip-types'  webpack -c ./webpack.config.ts

    Node.js 버전 22.7.0부터는 --no-experimental-strip-types 플래그가 필수입니다.

  3. Node.js 22.7.0 이상 버전에서 Node.js의 내장 변환 유형 기능을 사용하는 방법:

    열거형 선언, 매개변수 속성 등과 같이 JavaScript 코드 생성이 필요한, 지울 수 없는 TypeScript 구문의 변환을 가능하게 합니다.

    NODE_OPTIONS='--experimental-transform-types' webpack --disable-interpret -c ./webpack.config.ts

TypeScript Path Aliases

5.105.0+

tsconfig.json 파일에서 compilerOptions.paths 또는 compilerOptions.baseUrl을 사용하여 임포트 별칭을 생성하는 경우, webpack 5.105 버전부터는 webpack이 resolve.tsconfig 파일을 통해 이러한 별칭을 직접 읽을 수 있습니다. 따라서 기존의 tsconfig-paths-webpack-plugin 플러그인은 더 이상 사용하지 않아야 합니다.

resolve.tsconfigboolean | string | object 값을 허용합니다.

webpack.config.ts

export default {
  resolve: {
    tsconfig: true, // tsconfig.json 파일을 자동으로 찾습니다.
  },
};

특정 파일을 가리키는 문자열을 전달합니다(모노레포 환경에서 유용).

export default {
  resolve: {
    tsconfig: "./tsconfig.app.json",
  },
};

TypeScript 프로젝트 참조를 해결하기 위해 객체를 전달하세요(https://www.typescriptlang.org/docs/handbook/project-references.html).

export default {
  resolve: {
    tsconfig: {
      configFile: "./tsconfig.json",
      references: "auto", // tsconfig에서 참조를 상속받거나 경로 배열을 전달합니다.
    },
  },
};

tsconfig.json

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

위와 같이 하면 @/components/Button은 추가 플러그인이나 resolve.alias에 별칭을 중복 지정할 필요 없이 src/components/Button으로 해석됩니다.

Migrating from tsconfig-paths-webpack-plugin

현재 tsconfig-paths-webpack-plugin을 사용하고 있다면, 내장된 resolve.tsconfig 옵션으로 대체할 수 있습니다.

- 'tsconfig-paths-webpack-plugin'에서 TsconfigPathsPlugin을 가져옵니다.

  export default {
    resolve: {
-     plugins: [new TsconfigPathsPlugin()],
+     // 프로젝트 루트에서 tsconfig.json 파일을 자동으로 찾습니다.
+     tsconfig: true,
+
+     // 또는 명시적으로 하나를 가리키십시오.
+     // tsconfig: './tsconfig.app.json'
    },
  };

그런 다음 프로젝트에서 해당 패키지를 제거할 수 있습니다.

npm uninstall tsconfig-paths-webpack-plugin

Loader

ts-loader

이 가이드에서는 ts-loader를 사용하여 다른 웹 애셋 import 같은 추가적인 webpack 기능을 조금 더 쉽게 활성화 할 수 있습니다.

이미 babel-loader 사용하여 코드를 트랜스파일 하는 경우라면 @babel/preset-typescript를 사용하여 Babel이 추가 로더를 사용하는 대신 JavaScript와 TypeScript 파일을 모두 처리하도록 합니다. ts-loader와 달리, 기본 @babel/plugin-transform-typescript 플러그인은 어떠한 타입 검사도 수행하지 않습니다.

Source Maps

소스맵에 대한 자세한 내용은 개발 가이드를 참고하세요.

소스맵을 사용하려면 TypeScript가 컴파일된 JavaScript 파일로 인라인 소스맵을 출력하도록 설정해야 합니다. TypeScript 설정에 다음 내용을 꼭 추가해야합니다.

tsconfig.json

  {
    "compilerOptions": {
      "outDir": "./dist/",
+     "sourceMap": true,
      "noImplicitAny": true,
      "module": "esnext",
      "moduleResolution": "bundler",
      "target": "esnext",
      "jsx": "react-jsx",
      "allowJs": true,
  },
    "include": ["src/**/*"],
    "exclude": ["node_modules"]
  }

이제 webpack에 이러한 소스맵을 추출해 최종 번들에 포함되도록 지시해야 합니다.

webpack.config.ts

 import path from "node:path";
 import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

  export default {
    entry: './src/index.ts',
+   devtool: 'inline-source-map',
    module: {
      rules: [
        {
          test: /\.tsx?$/,
          use: 'ts-loader',
          exclude: /node_modules/,
        },
      ],
    },
    resolve: {
      extensions: [ '.tsx', '.ts', '.js' ],
    },
    output: {
      filename: 'bundle.js',
      path: path.resolve(__dirname, 'dist'),
    },
  };

자세한 내용은 개발자 도구 문서를 참고하세요.

Client types

TypeScript 코드에서 import.meta.webpack과 같은 webpack 관련 기능을 사용할 수 있습니다. 그리고 webpack은 이에 대한 타입도 제공합니다. TypeScript reference 지시문을 추가하여 선언하면 됩니다.

/// <reference types="webpack/module" />
console.log(import.meta.webpack); // 위에서 선언된 참조가 없으면 TypeScript에서 에러가 발생합니다.

프로젝트 전체에 타입 지정을 활성화하려면 tsconfig.json 파일의 compilerOptions.typeswebpack/module을 추가하세요.

  {
    "compilerOptions": {
      "types": [
+       "webpack/module"
      ]
    }
  }

Using Third Party Libraries

npm으로부터 타사 라이브러리를 설치할 때는 해당 라이브러리에 대한 타입 정의를 설치해야 한다는 사실을 기억해야 합니다.

예를 들어 lodash를 사용하려면 다음 명령을 실행하여 해당 타입 정의를 설치해야 합니다.

npm install --save-dev @types/lodash

npm 패키지가 이미 패키지 번들에 선언 유형을 포함하고 있는 경우 해당 @types 패키지를 다운로드할 필요가 없습니다. 자세한 내용은 TypeScript 변경 로그 블로그를 참고하세요.

Importing Other Assets

TypeScript와 함께 비코드 애셋을 사용하려면 이러한 import에 대한 타입을 연기해야 합니다. 이를 위해서 프로젝트에 TypeScript에 대한 사용자 정의를 나타내는 custom.d.ts 파일이 필요합니다. .svg 파일에 대한 선언을 설정해 보겠습니다.

custom.d.ts

declare module "*.svg" {
  const content: any;
  export default content;
}

여기에서는 .svg로 끝나는 import를 지정하고 모듈의 contentany로 정의하여 SVG를 위한 새로운 모듈을 선언합니다. 타입을 문자열로 정의하여 URL이라는 것을 더 명확하게 할 수 있습니다. CSS, SCSS, JSON 등을 포함한 다른 애셋에도 동일한 개념이 적용됩니다.

Build Performance

빌드 도구에 대한 빌드 성능 가이드를 참고하세요.

Edit this page·
« Previous
Shimming

10 Contributors

morsdycekkamalimtriverabyzykEugeneHlushkochenxsansnitin315tusharthakur04ThierryRakotomananavalentina-buoro

Translators