SWC provides an official JSON Schema for the configuration file.
{
"$schema": "https://swc.rs/schema.json",
}
编译
使用 SWC 进行编译无需额外配置即可开箱即用。你也可以选择覆盖默认配置。以下是默认设置:
{
"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
示例:
{
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": true,
},
"externalHelpers": true
},
"env": {
"targets": "Chrome >= 48"
}
}
-
多个查询条件:
string[]
-
各浏览器版本:
Map<String, Version>
以 chrome 79
为目标环境的示例。
{
"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
转换的示例。
{
"env": {
"targets": {
"chrome": "79",
},
"include": [
"transform-async-to-generator",
"transform-regenerator",
],
},
}
env.exclude
可选。
类型:string[]
排除的特性或模块。
env.coreJs
可选。
类型:string
{
"jsc": {
"parser": {
"syntax": "ecmascript",
"jsx": true
}
},
"env": {
"mode": "usage",
"coreJs": "3.26.1"
}
}
env.path
可选。 目前无操作。
env.shippedProposals
可选。 类型:布尔值
env.forceAllTransforms
可选。 类型:布尔值
env.bugfixes
可选。 类型:布尔值
启用 bug 修复。
jsc.externalHelpers
{
"jsc": {
"externalHelpers": true
}
}
输出代码可能依赖于辅助函数以支持目标环境。默认情况下,辅助函数会被内联到需要它的输出文件中。
你可以通过启用 externalHelpers
来使用外部模块中的辅助函数,辅助函数代码将由输出文件从 node_modules/@swc/helpers
导入。
在打包时,此选项将显著减小文件体积。
你必须在 @swc/core
之外添加 @swc/helpers
作为依赖。
jsc.parser
typescript
{
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": false,
"decorators": false,
"dynamicImport": false
}
}
}
ecmascript
{
"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 开始,你可以通过此字段指定目标环境。
{
"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),如果你的代码不符合这些假设,可能会得到意外结果。
- privateFieldsAsProperties (opens in a new tab)
- setPublicClassFields (opens in a new tab)
- constantSuper (opens in a new tab)
- noDocumentAll (opens in a new tab)
- pureGetters (opens in a new tab)
- objectRestNoSymbols (opens in a new tab)
- setSpreadProperties (opens in a new tab)
- ignoreFunctionName
- ignoreFunctionLength (opens in a new tab)
- ignoreToPrimitiveHint (opens in a new tab)
- mutableTemplateObject (opens in a new tab)
- noClassCalls (opens in a new tab)
- setClassMethods (opens in a new tab)
- superIsCallableConstructor (opens in a new tab)
- iterableIsArray (opens in a new tab)
{
"jsc": {
"loose": true
}
}
jsc.transform
{
"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)类装饰器语法和行为。
{
"jsc": {
"parser": {
"syntax": "ecmascript",
"decorators": true
},
"transform": {
"legacyDecorator": true
}
}
}
jsc.transform.decoratorMetadata
此功能需要 v1.2.13+
。
如果你在使用 TypeScript 和装饰器,并启用了 emitDecoratorMetadata
,你可以使用 swc
进行更快的迭代:
{
"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
在作用域内。
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
{
"jsc": {
"transform": {
"constModules": {
"globals": {
"@ember/env-flags": {
"DEBUG": "true"
},
"@ember/features": {
"FEATURE_A": "false",
"FEATURE_B": "true"
}
}
}
}
}
}
然后,像这样的源代码:
import { DEBUG } from "@ember/env-flags";
import { FEATURE_A, FEATURE_B } from "@ember/features";
console.log(DEBUG, FEATURE_A, FEATURE_B);
将被转换为:
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
的同时跳过优化。
{
"jsc": {
"transform": {
"optimizer": {
"simplify": false,
"globals": {
"vars": {
"__DEBUG__": "true"
}
}
}
}
}
}
jsc.transform.optimizer.globals
需要
v1.2.101+
vars
- 要内联的变量。typeofs
- 如果你设置{ "window": "object" }
,typeof window
将被替换为"object"
。
{
"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。
{
"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
路径必须指定为绝对路径。
jsc.minify
需要
v1.2.67+
有关更多详细信息,请参见 压缩文档。
jsc.experimental
jsc.experimental.keepImportAttributes
保留导入属性。 由于导入属性尚未被 ECMAScript 规范覆盖,此功能尚处于实验阶段。
jsc.experimental.plugins
它遵循 node.js 的解析规则。
指定插件名称,如
{
"jsc": {
"experimental": {
"plugins": [
["@swc/plugin-styled-jsx", {}]
]
}
}
}
styled-jsx
之所以有效,是因为它作为 @swc/plugin-styled-jsx
发布。
jsc.experimental.cacheRoot
指定 SWC 存储其中间缓存文件的位置。
目前只有转换插件使用此功能。如果未指定,SWC 将创建 .swc
目录。
{
"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 装饰器。
{
"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 文件,例如:
{
"test": ".*\\.ts$",
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": false,
"decorators": true,
"dynamicImport": true
}
}
}
test
类型:Regex / Regex[]
{
"test": ".*\\.ts$",
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": false,
"decorators": true,
"dynamicImport": true
}
}
}
exclude
类型:Regex / Regex[]
{
"exclude": [".*\\.js$", ".*\\.map$"],
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": false,
"decorators": true,
"dynamicImport": true
}
}
}
sourceMaps
需要
v1.2.50+
通过将 sourceMaps: true
或 sourceMaps: 'inline'
添加到 .swcrc
来启用源映射。
{
"sourceMaps": true
}
inlineSourcesContent
需要
v1.2.101+
默认为 true
。如果你希望 swc
将文件内容存储到源映射中,可以将 inlineSourcesContent
设置为 true
。
{
"sourceMaps": true,
"inlineSourcesContent": true
}
isModule
可选值:true
, false
, "unknown"
用于将输入视为模块或脚本。
如果设置为 unknown
,则当输入为 ESM 时视为 Module
,否则视为 Script
。