💡

SWC provides an official JSON Schema for the configuration file.

.swcrc

{
  "$schema": "https://swc.rs/schema.json",
}

编译

使用 SWC 进行编译无需额外配置即可开箱即用。你也可以选择覆盖默认配置。以下是默认设置：

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": false,
      "dynamicImport": false,
      "privateMethod": false,
      "functionBind": false,
      "exportDefaultFrom": false,
      "exportNamespaceFrom": false,
      "decorators": false,
      "decoratorsBeforeExport": false,
      "topLevelAwait": false,
      "importMeta": false,
      "preserveAllComments": false
    },
    "transform": null,
    "target": "es5",
    "loose": false,
    "externalHelpers": false,
    // 需要 v1.2.50 或更高版本，且目标环境需为 es2016 或更高。
    "keepClassNames": false
  },
  "isModule": false
}

环境配置

SWC 提供了 preset-env 的替代方案。你可以

设置目标浏览器
使用 browserslist
控制转换

通过 env 配置项实现。注意，此配置项与 jsc.target 不兼容。

`env.targets`

可选值：

查询条件：string

示例：

.swcrc

{
    "jsc": {
        "parser": {
            "syntax": "typescript",
            "tsx": true,
        },
        "externalHelpers": true
    },
    "env": {
        "targets": "Chrome >= 48"
    }
}

多个查询条件：string[]
各浏览器版本：Map<String, Version>

以 chrome 79 为目标环境的示例。

.swcrc

{
    "env": {
        "targets": {
            "chrome": "79",
        }
    },
}

`env.mode`

可选。可选值："usage" | "entry" | false，默认为 false。

`env.debug`

可选。类型：布尔值

启用调试日志记录。

`env.dynamicImport`

可选。类型：布尔值

`env.loose`

可选。类型：布尔值

启用松散模式。另见 jsc.loose。

`env.skip`

可选。类型：string[]

`env.include`

可选。类型：string[]

包含的特性或模块。

以 chrome 79 为目标环境并启用 async/yield 转换的示例。

.swcrc

{
    "env": {
        "targets": {
            "chrome": "79",
        },
        "include": [
            "transform-async-to-generator",
            "transform-regenerator",
        ],
    },
}

`env.exclude`

可选。类型：string[]

排除的特性或模块。

`env.coreJs`

可选。类型：string

.swcrc

{
    "jsc": {
        "parser": {
            "syntax": "ecmascript",
            "jsx": true
        }
    },
    "env": {
        "mode": "usage",
        "coreJs": "3.26.1"
    }
}

`env.path`

可选。目前无操作。

`env.shippedProposals`

可选。类型：布尔值

`env.forceAllTransforms`

可选。类型：布尔值

`env.bugfixes`

可选。类型：布尔值

启用 bug 修复。

jsc.externalHelpers

.swcrc

{
  "jsc": {
    "externalHelpers": true
  }
}

输出代码可能依赖于辅助函数以支持目标环境。默认情况下，辅助函数会被内联到需要它的输出文件中。

你可以通过启用 externalHelpers 来使用外部模块中的辅助函数，辅助函数代码将由输出文件从 node_modules/@swc/helpers 导入。

在打包时，此选项将显著减小文件体积。

你必须在 @swc/core 之外添加 @swc/helpers 作为依赖。

jsc.parser

typescript

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": false,
      "decorators": false,
      "dynamicImport": false
    }
  }
}

ecmascript

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": false,
      "dynamicImport": false,
      "privateMethod": false,
      "functionBind": false,
      "classPrivateProperty": false,
      "exportDefaultFrom": false,
      "exportNamespaceFrom": false,
      "decorators": false,
      "decoratorsBeforeExport": false,
      "importMeta": false
    }
  }
}

jsc.target

从 @swc/core v1.0.27 开始，你可以通过此字段指定目标环境。

.swcrc

{
  "jsc": {
    // 禁用 es3 / es5 / es2015 转换
    "target": "es2016"
  }
}

jsc.loose

从 @swc/core v1.1.4 开始，你可以通过启用 jsc.loose 来启用“松散”转换，其工作方式类似于 babel-preset-env 的松散模式 (opens in a new tab)。

⚠️

在松散模式下默认做出以下假设 (opens in a new tab)，如果你的代码不符合这些假设，可能会得到意外结果。

.swcrc

{
  "jsc": {
    "loose": true
  }
}

jsc.transform

.swcrc

{
  "jsc": {
    "transform": {
      "react": {
        "pragma": "React.createElement",
        "pragmaFrag": "React.Fragment",
        "throwIfNamespace": true,
        "development": false,
        "useBuiltins": false
      },
      "optimizer": {
        "globals": {
          "vars": {
            "__DEBUG__": "true"
          }
        }
      }
    }
  }
}

jsc.transform.legacyDecorator

你可以使用旧版（stage 1）类装饰器语法和行为。

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true
    }
  }
}

jsc.transform.decoratorMetadata

此功能需要 v1.2.13+。

如果你在使用 TypeScript 和装饰器，并启用了 emitDecoratorMetadata，你可以使用 swc 进行更快的迭代：

.swcrc

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true,
      "decoratorMetadata": true
    }
  }
}

jsc.transform.react

jsc.transform.react.runtime

可选值：automatic, classic。这会影响 JSX 源代码的编译方式。

默认为 classic。
使用 runtime: automatic 以使用 JSX 运行时模块（例如 React 17 引入的 react/jsx-runtime）。
使用 runtime: classic 以使用 React.createElement 代替——使用此选项时，你必须确保在使用 JSX 时 React 在作用域内。

了解更多 (opens in a new tab)。

jsc.transform.react.importSource

默认为 react。
当使用 runtime: automatic 时，确定导入的运行时库。
此选项可以通过 @jsxImportSource foo 覆盖。

jsc.transform.react.pragma

默认为 React.createElement。
当使用 runtime: classic 时，替换编译 JSX 表达式时使用的函数。
此选项可以通过 @jsx foo 覆盖。

jsc.transform.react.pragmaFrag

默认为 React.Fragment
替换编译 JSX 片段时使用的组件。
此选项可以通过 @jsxFrag foo 覆盖。

jsc.transform.react.throwIfNamespace

切换是否在使用 XML 命名空间标签名时抛出错误。例如：<f:image />

尽管 JSX 规范允许这样做，但由于 React 的 JSX 目前不支持此功能，因此默认禁用。

jsc.transform.react.development

切换由 JSX 生成的元素上的调试属性 __self 和 __source，这些属性由 React Developer Tools 等开发工具使用。

当与 swc-loader 一起使用时，此选项会根据 Webpack 的 mode 设置自动设置。参见使用 swc 与 webpack。

jsc.transform.react.useBuiltins

使用 Object.assign() 代替 _extends。默认为 false。

jsc.transform.react.refresh

启用 react-refresh (opens in a new tab) 相关转换。由于此功能尚处于实验阶段，默认为 false。

传递 refresh: true 以启用此功能，或传递包含以下内容的对象：

interface ReactRefreshConfig {
  refreshReg: String;
  refreshSig: String;
  emitFullSignatures: boolean;
}

jsc.transform.constModules

.swcrc

{
  "jsc": {
    "transform": {
      "constModules": {
        "globals": {
          "@ember/env-flags": {
            "DEBUG": "true"
          },
          "@ember/features": {
            "FEATURE_A": "false",
            "FEATURE_B": "true"
          }
        }
      }
    }
  }
}

然后，像这样的源代码：

source.js

import { DEBUG } from "@ember/env-flags";
import { FEATURE_A, FEATURE_B } from "@ember/features";
 
console.log(DEBUG, FEATURE_A, FEATURE_B);

将被转换为：

output.js

console.log(true, false, true);

jsc.transform.optimizer

SWC 优化器假设：

它是一个模块或被包裹在 IIFE 中。
访问（获取）全局变量不会产生副作用。这与 Google Closure Compiler 的假设相同。
你不会向字面量（如数字字面量、正则表达式或字符串字面量）添加字段。
文件以 gzip 格式提供。

SWC 不会专注于减少非 gzip 文件的大小。

将此设置为 undefined 会跳过优化器阶段。

jsc.transform.optimizer.simplify

需要 v1.2.101+

你可以将此设置为 false 以在使用 inline_globals 的同时跳过优化。

.swcrc

{
  "jsc": {
    "transform": {
      "optimizer": {
        "simplify": false,
        "globals": {
          "vars": {
            "__DEBUG__": "true"
          }
        }
      }
    }
  }
}

jsc.transform.optimizer.globals

需要 v1.2.101+

vars - 要内联的变量。
typeofs - 如果你设置 { "window": "object" }，typeof window 将被替换为 "object"。

.swcrc

{
  "jsc": {
    "transform": {
      "optimizer": {
        "globals": {
          "vars": {
            "__DEBUG__": "true"
          }
        }
      }
    }
  }
}

然后，你可以像这样使用它：npx swc '__DEBUG__' --filename input.js。

jsc.transform.optimizer.jsonify

需要 v1.1.1+

minCost - 如果解析纯对象字面量的成本大于此值，对象字面量将被转换为 JSON.parse('{"foo": "bar"}')。默认为 1024。

.swcrc

{
  "jsc": {
    "transform": {
      "optimizer": {
        "jsonify": {
          "minCost": 0
        }
      }
    }
  }
}

这将把所有纯对象字面量转换为 JSON.parse("")。

jsc.keepClassNames

需要 v1.2.50+ 且目标环境需为 es2016 或更高

启用此选项将使 swc 保留原始类名。

jsc.paths

需要 v1.2.62+

语法与 tsconfig.json 相同：了解更多 (opens in a new tab)。

需要 jsc.baseUrl。见下文。

jsc.baseUrl

路径必须指定为绝对路径。

了解更多 (opens in a new tab)。

jsc.minify

需要 v1.2.67+

有关更多详细信息，请参见压缩文档。

jsc.experimental

jsc.experimental.keepImportAttributes

保留导入属性。由于导入属性尚未被 ECMAScript 规范覆盖，此功能尚处于实验阶段。

jsc.experimental.plugins

它遵循 node.js 的解析规则。

指定插件名称，如

.swcrc

{
  "jsc": {
    "experimental": {
      "plugins": [
        ["@swc/plugin-styled-jsx", {}]
      ]
    }
  }
}

styled-jsx 之所以有效，是因为它作为 @swc/plugin-styled-jsx 发布。

jsc.experimental.cacheRoot

指定 SWC 存储其中间缓存文件的位置。

目前只有转换插件使用此功能。如果未指定，SWC 将创建 .swc 目录。

.swcrc

{
  "jsc": {
    "experimental": {
      "cacheRoot": "node_modules/.cache/swc"
    }
  }
}

jsc.preserveAllComments

指示在编译期间应保留所有注释。源文件中的注释可能会被移动，以保持其从源文件到编译输出的相对位置。此功能对于需要注释保持相对接近源代码的转译非常有用：例如，带有 istanbul-ignore 覆盖注释的测试文件。

jsc.transform.useDefineForClassFields

可选值：

true:

class Foo {
  init = 3;
}
 
console.log(Foo.init)

将被编译为

class Foo {
    constructor(){
        // 辅助函数
        _defineProperty(this, "init", 3);
    }
}
console.log(Foo.init);

false:

class Foo {
  init = 3;
}
 
console.log(Foo.init)

将被编译为

class Foo {
    constructor(){
        this.init = 3;
    }
}
console.log(Foo.init);

jsc.transform.decoratorVersion

从 v1.3.47 开始，你可以使用 stage 3 装饰器。

.swcrc

{
    "jsc": {
        "parser": {
            "syntax": "ecmascript",
            "decorators": true
        },
        "transform": {
            "decoratorVersion": "2022-03"
        }
    }
}

可选值：

"2021-12"（默认）

旧版装饰器。

"2022-03"

Stage 3 装饰器。

jsc.output

jsc.output.charset

可选值：utf8, ascii。

此选项可用于保持输出仅为 ASCII 字符。

多入口

需要 v1.0.47+

[
  {
    "test": ".*\\.js$",
    "module": {
      "type": "commonjs"
    }
  },
  {
    "test": ".*\\.ts$",
    "module": {
      "type": "amd"
    }
  }
]

这使得 SWC 将 JavaScript 文件编译为 CommonJS 模块，并将 TypeScript 文件编译为 AMD 模块。

注意，test 选项可用于仅转译 TypeScript 文件，例如：

.swcrc

{
  "test": ".*\\.ts$",
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": false,
      "decorators": true,
      "dynamicImport": true
    }
  }
}

test

类型：Regex / Regex[]

.swcrc

{
  "test": ".*\\.ts$",
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": false,
      "decorators": true,
      "dynamicImport": true
    }
  }
}

exclude

类型：Regex / Regex[]

.swcrc

{
  "exclude": [".*\\.js$", ".*\\.map$"],
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": false,
      "decorators": true,
      "dynamicImport": true
    }
  }
}

sourceMaps

需要 v1.2.50+

通过将 sourceMaps: true 或 sourceMaps: 'inline' 添加到 .swcrc 来启用源映射。

.swcrc

{
  "sourceMaps": true
}

inlineSourcesContent

需要 v1.2.101+

默认为 true。如果你希望 swc 将文件内容存储到源映射中，可以将 inlineSourcesContent 设置为 true。

.swcrc

{
  "sourceMaps": true,
  "inlineSourcesContent": true
}

isModule

可选值：true, false, "unknown"

用于将输入视为模块或脚本。如果设置为 unknown，则当输入为 ESM 时视为 Module，否则视为 Script。

.swcrc 支持的浏览器