> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# @aspect_rules_swc//swc:defs.bzl

> Bazel rules_swc API: swc rule and macros to compile TypeScript and JavaScript with the SWC CLI under Bazel using .swcrc configuration.

<Callout icon="book">
  Documentation for [@aspect\_rules\_swc@v2.6.1](https://registry.bazel.build/modules/aspect_rules_swc/2.6.1) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_swc/blob/v2.6.1/swc/defs.bzl)
</Callout>

API for running the SWC cli under Bazel

The simplest usage relies on the `swcrc` attribute automatically discovering `.swcrc`:

```python theme={null}
load("@aspect_rules_swc//swc:defs.bzl", "swc")

swc(
    name = "compile",
    srcs = ["file.ts"],
)
```

## Rule: `swc_compile`

Underlying rule for the `swc` macro.

Most users should use [swc](#swc) instead, as it predicts the output files
and has convenient default values.

Use this if you need more control over how the rule is called,
for example to set your own output labels for `js_outs`.

### Attributes

<ParamField body="name" type="name" required>
  A unique name for this target.
</ParamField>

<ParamField body="srcs" type="list of labels" required>
  source files, typically .ts files in the source tree
</ParamField>

<ParamField body="args" type="list of strings" default={`[]`}>
  Additional arguments to pass to swcx cli (NOT swc!).

  NB: this is not the same as the CLI arguments for @swc/cli npm package.
  For performance, rules\_swc does not call a Node.js program wrapping the swc rust binding.
  Instead, we directly spawn the (somewhat experimental) native Rust binary shipped inside the
  @swc/core npm package, which the swc project calls "swcx"
  Tracking issue for feature parity: [https://github.com/swc-project/swc/issues/4017](https://github.com/swc-project/swc/issues/4017)
</ParamField>

<ParamField body="source_maps" type="string" default={`false`}>
  Create source map files for emitted JavaScript files.

  see [https://swc.rs/docs/usage/cli#--source-maps--s](https://swc.rs/docs/usage/cli#--source-maps--s)
</ParamField>

<ParamField body="source_root" type="string" default={`""`}>
  Specify the root path for debuggers to find the reference source code.

  see [https://swc.rs/docs/usage/cli#--source-root](https://swc.rs/docs/usage/cli#--source-root)

  If not set, then the directory containing the source file is used.
</ParamField>

<ParamField body="output_dir" type="boolean" default={`False`}>
  Whether to produce a directory output rather than individual files.

  If out\_dir is also specified, it is used as the name of the output directory.
  Otherwise, the directory is named the same as the target.
</ParamField>

<ParamField body="data" type="list of labels" default={`[]`}>
  Runtime dependencies to include in binaries/tests that depend on this target.

  Follows the same semantics as `js_library` `data` attribute. See
  [https://docs.aspect.build/rulesets/aspect\_rules\_js/docs/js\_library#data](https://docs.aspect.build/rulesets/aspect_rules_js/docs/js_library#data) for more info.
</ParamField>

<ParamField body="swcrc" type="label" default={`None`}>
  label of a configuration file for swc, see [https://swc.rs/docs/configuration/swcrc](https://swc.rs/docs/configuration/swcrc)
</ParamField>

<ParamField body="plugins" type="list of labels" default={`[]`}>
  swc compilation plugins, created with swc\_plugin rule
</ParamField>

<ParamField body="out_dir" type="string" default={`""`}>
  With output\_dir=False, output files will have this directory prefix.

  With output\_dir=True, this is the name of the output directory.
</ParamField>

<ParamField body="root_dir" type="string" default={`""`}>
  a subdirectory under the input package which should be consider the root directory of all the input files
</ParamField>

<ParamField body="emit_isolated_dts" type="boolean" default={`False`}>
  Emit .d.ts files instead of .js for TypeScript sources

  EXPERIMENTAL: this API is undocumented, experimental and may change without notice
</ParamField>

<ParamField body="default_ext" type="string" default={`""`}>
  Default extension for output files.

  If a source file does not indicate a specific module type, this extension is used.

  If unset, extensions will be determined based on the `js_outs` outputs attribute
  or source file extensions.
</ParamField>

<ParamField body="allow_js" type="boolean" default={`True`}>
  Allow JavaScript sources to be transpiled.

  If False, only TypeScript sources will be transpiled.
</ParamField>

<ParamField body="js_outs" type="list of labels" default={`[]`}>
  list of expected JavaScript output files.

  There should be one for each entry in srcs.
</ParamField>

<ParamField body="map_outs" type="list of labels" default={`[]`}>
  list of expected source map output files.

  Can be empty, meaning no source maps should be produced.
  If non-empty, there should be one for each entry in srcs.
</ParamField>

<ParamField body="dts_outs" type="list of labels" default={`[]`}>
  list of expected TypeScript declaration files.

  Can be empty, meaning no dts files should be produced.
  If non-empty, there should be one for each entry in srcs.
</ParamField>

## Function: `swc`

Execute the SWC compiler

### Parameters

<ParamField body="name" type="unknown" required>
  A name for this target
</ParamField>

<ParamField body="srcs" type="unknown" required>
  List of labels of TypeScript source files.
</ParamField>

<ParamField body="args" type="unknown" default={`[]`}>
  Additional options to pass to `swcx` cli, see [https://github.com/swc-project/swc/discussions/3859](https://github.com/swc-project/swc/discussions/3859)
  Note: we do **not** run the [NodeJS wrapper `@swc/cli`](https://swc.rs/docs/usage/cli)
</ParamField>

<ParamField body="data" type="unknown" default={`[]`}>
  Files needed at runtime by binaries or tests that transitively depend on this target.
  See [https://bazel.build/reference/be/common-definitions#typical-attributes](https://bazel.build/reference/be/common-definitions#typical-attributes)
</ParamField>

<ParamField body="plugins" type="unknown" default={`[]`}>
  List of plugin labels created with `swc_plugin`.
</ParamField>

<ParamField body="output_dir" type="unknown" default={`False`}>
  Whether to produce a directory output rather than individual files.

  If `out_dir` is set, then that is used as the name of the output directory.
  Otherwise, the output directory is named the same as the target.
</ParamField>

<ParamField body="swcrc" type="unknown" default={`None`}>
  Label of a .swcrc configuration file for the SWC cli, see [https://swc.rs/docs/configuration/swcrc](https://swc.rs/docs/configuration/swcrc)
  Instead of a label, you can pass a dictionary matching the JSON schema.
  If this attribute isn't specified, and a file `.swcrc` exists in the same folder as this rule, it is used.

  Note that some settings in `.swcrc` also appear in `tsconfig.json`.
  See the notes in \[/docs/tsconfig.md].
</ParamField>

<ParamField body="source_maps" type="unknown" default={`False`}>
  If set, the --source-maps argument is passed to the SWC cli with the value.
  See [https://swc.rs/docs/usage/cli#--source-maps--s](https://swc.rs/docs/usage/cli#--source-maps--s).
  True/False are automaticaly converted to "true"/"false" string values the cli expects.
</ParamField>

<ParamField body="out_dir" type="unknown" default={`None`}>
  The base directory for output files relative to the output directory for this package.

  If output\_dir is True, then this is used as the name of the output directory.
</ParamField>

<ParamField body="root_dir" type="unknown" default={`None`}>
  A subdirectory under the input package which should be considered the root directory of all the input files
</ParamField>

<ParamField body="default_ext" type="unknown" default={`.js`}>
  The default extension to use for output files. If not set, the default is ".js".
</ParamField>

<ParamField body="allow_js" type="unknown" default={`True`}>
  If `True` (default), then .js/.mjs/.cjs input files are transpiled. If `False`,
  they are ignored. This can be used to mimic the behavior of tsc when using `ts_project(transpiler)`.
</ParamField>

<ParamField body="kwargs" type="unknown">
  additional keyword arguments passed through to underlying [`swc_compile`](#swc_compile), eg. `visibility`, `tags`
</ParamField>

## Function: `swc_plugin`

Configure an SWC plugin

### Parameters

<ParamField body="name" type="unknown" required>
  A name for this target
</ParamField>

<ParamField body="srcs" type="unknown" default={`[]`}>
  Plugin files. Either a directory containing a package.json pointing at a wasm file
  as the main entrypoint, or a wasm file. Usually a linked npm package target via rules\_js.
</ParamField>

<ParamField body="config" type="unknown" default={`{}`}>
  Optional configuration dict for the plugin. This is passed as a JSON object into the
  `jsc.experimental.plugins` entry for the plugin.
</ParamField>

<ParamField body="kwargs" type="unknown">
  additional keyword arguments passed through to underlying rule, eg. `visibility`, `tags`
</ParamField>