Skip to content
文档
配置
编译
💡

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)

.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: truesourceMaps: '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