> For AI agents: the complete documentation index is available at https://rspack.rs/zh/llms.txt, the full documentation bundle is available at https://rspack.rs/zh/llms-full.txt.

# TypeScript

## 如何使用

通过 [`builtin:swc-loader`](https://rspack.rs/zh/guide/features/builtin-swc-loader.md) 可以开启对 TypeScript 的支持。

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|ts)$/,
        exclude: [/node_modules/],
        loader: 'builtin:swc-loader',
        options: {
          detectSyntax: 'auto',
        },
      },
    ],
  },
};
```

## 仅转译（transpile only）

`builtin:swc-loader` 仅会对源码进行转译，因此你需要使用其他工具（如：tsc）完成对源码的类型检查。

## 开启 isolatedModules

`builtin:swc-loader` 会独立转译每个模块。建议在 `tsconfig.json` 中开启 [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules)，让 TypeScript 检查无法安全地进行单文件转译的代码。

```json title="tsconfig.json"
{
  "compilerOptions": {
    "isolatedModules": true
  }
}
```

## 类型检查

你可以使用 [ts-checker-rspack-plugin](https://github.com/rstackjs/ts-checker-rspack-plugin) 在编译过程中执行 TypeScript 类型检查。然而，需要注意的是，特别是对于较大的项目，TypeScript 的类型检查可能非常耗时。这意味着类型检查所需的时间可能超过 Rspack 本身的构建时间。

如果你在开发模式下使用该插件，它将不会阻塞构建过程，你可以继续进行构建。但是，在构建模式下，该插件将会阻塞构建，直到类型检查完成，所以可能会导致构建时间变长。

根据你的实际需求，你应该决定是否启用该插件。如果类型检查过程成为构建过程的瓶颈，我们建议使用 TypeScript 的增量构建功能。该功能可以通过仅分析自上次构建以来修改的文件来大大加快类型检查的速度。

要启用 TypeScript 的增量构建，你可以在独立使用 `tsc --incremental` 或者在插件里[使用 incremental mode](https://github.com/rstackjs/ts-checker-rspack-plugin#enabling-incremental-mode)。

启用增量构建可以帮助减少类型检查的时间，特别是当只有少数文件被修改时。这样，你可以在优化构建过程的同时，不会损失类型检查的好处。

请记住，在你的具体项目中，需要权衡构建速度和类型检查准确性之间的权衡，并据此选择最佳方法。

## JSX/TSX

通过 [`builtin:swc-loader`](https://rspack.rs/zh/guide/features/builtin-swc-loader.md) 可以开启对 JSX 和 TSX 的支持。

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(?:js|mjs|jsx|ts|tsx)$/,
        use: {
          loader: 'builtin:swc-loader',
          options: {
            detectSyntax: 'auto',
            jsc: {
              transform: {
                react: {
                  pragma: 'React.createElement',
                  pragmaFrag: 'React.Fragment',
                  throwIfNamespace: true,
                  development: false,
                },
              },
            },
          },
        },
      },
    ],
  },
};
```

## Alias

点击 [resolve.tsConfig](https://rspack.rs/zh/config/resolve.md#resolvetsconfig) 查看详情。

## Client 类型

在 TypeScript 代码中，可以获取到 Rspack 特有的功能，例如 [import.meta.glob](https://rspack.rs/zh/api/runtime-api/module-variables.md#importmetaglob)。

Rspack 通过 `@rspack/core/module` 提供 Client 模块的类型，你可以通过不同方法来声明它们：

1. 添加 TypeScript reference 指令来声明：

   在全局的 d.ts 声明文件中添加以下内容：

   ```ts title="src/app-env.d.ts"
   /// <reference types="@rspack/core/module" />
   ```

   然后便可以在任意 TypeScript 文件中使用：

   ```ts title="src/index.ts"
   const modules = import.meta.glob('./dir/*.js'); // 如果没有上面的引用声明，TypeScript 将会抛出错误
   ```

2. 你也可以将 `@rspack/core/module` 添加到 tsconfig.json 的 `types` 字段中。具体可参考 [tsconfig types 文档](https://www.typescriptlang.org/tsconfig/#types)。

   ```json title="tsconfig.json"
   {
     "compilerOptions": {
       "types": ["@rspack/core/module"]
     }
   }
   ```