Introducing experimental native SWC CLI

[kwonoj]

Introduction

SWC currently provides its cli package @swc/cli. It is a wrapping node.js script to core node.js binding @swc/node. It is quite a common pattern to build CLI on top of the library we are offering, which also allows us to share core library to the application. However, it means every CLI invocation need to spend some time to warm up node.js process. Moreover, while SWC itself is agnostic to any javascript runtime, cli requires to install node.js as a dependency We spent some time writing a native CLI binary for SWC to attempt to resolve those. While it only supports very basic features I'd like to share it and would like to welcome any contributions.

Installation

Please note distribution needs more thought for actual release.

There are 2 ways to use new cli currently. First, if you have cargo installed you can install it via

$> cargo install swc_cli

// cli `swc` is available
$> swc --help

Or if you have node.js with npm or other package manager you can install it via

$> npm install @swc/core

// cli `swcx` is available in node_modules/.bin
$> npx swcx --help

Npm package's binary name is swcx. It is to avoid to conflict existing @swc/cli's binary entry swc. I expect it'll likely change with proper distribution later.

Using CLI

There is one major difference between @swc/cli and new binary. Previously swc was an entrypoint to SWC's compilation (transform). New CLI tries to consolidates all of the features of SWC with its subcommand.

$> swc --help

USAGE:
    swc.exe <SUBCOMMAND>

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

SUBCOMMANDS:
    compile    Run SWC's transformer
    help       Print this message or the help of the given subcommand(s)
    plugin     Commandline utilities for creating, building plugins

// Equivalent to `@swc/cli`'s `swc ...`
$> swc compile ...

// Other feature will be supported
$> swc bundle ...
$> swc minify ...

Option questions

It is early stage of development and there are lot of open questions need to be resolved.

• How will we distribute binary?
• Will @swc/core ships cli by default, or should be installed separately via @swc/cli?
• Potentially breaking changes for the supported cli options
• What'll be migration paths from existing cli?
• ...and potentially others

How to contribute

We welcome any contribution to improve, implement the remaining SWC CLI features. If you'd like to dive in, please check these.

1. Check subcommand we support (https://github.com/swc-project/swc/blob/main/crates/swc_cli/src/commands/mod.rs#L11), pick the feature to work on
2. Each command has an implementation under https://github.com/swc-project/swc/tree/main/crates/swc_cli/src/commands
3. Implement, or expand execute fn for new features, or fix (https://github.com/swc-project/swc/blob/main/crates/swc_cli/src/commands/plugin.rs#L120)

For compile subcommand, there is a predefined option from existing @swc/cli we need to port over (https://github.com/swc-project/swc/blob/main/crates/swc_cli/src/commands/compile.rs#L24). For other subcommands that is not fully determined yet, please suggest a proposal at https://github.com/swc-project/swc/discussions before making an actual implementation PR. We hope to make CLI's public interface to stay long without major breaking changes and want to start from minimal set of features.

FAQ

• Will this replace @swc/cli? : Eventually yes. However, we'll make an official announcement when it's ready. Until then @swc/cli will not be deprecated.
• Does this mean CI, or machines can compile / bundle JS code without node.js installed?: Yes.
• npx swcx still invokes node.js, isn't it?: Yes. We'll need to sort out how to distribute binary, while having linked node_modules/.bin will exist to easier access from npm ecosystem.

[RiESAEX]

when I try npx swcx --help I got a 'EACCES' error, the binary at/node_modules/@swc/core-darwin-arm64/swc is -rw-r--r--,
after I run chmod 755 swc and it works

[kwonoj]

🤦 I always forget chmod for the binary.

[RiESAEX]

I thought it will be fix in 1.2.161, but I just find it is still '-rw-r--r--'..

[kwonoj]

I don't have good answer for this 🤔 not sure why chmod didn't work.

[hochhaus]

This is great news @kwonoj. Would it be possible for this project to package the raw binary swc during releases for use cases where neither cargo nor node.js are installed?

[kwonoj]

Technically it isn't impossible and maybe one day we'll do, but we do not have active plan for it. Mainly due to distribution mechanism across all platforms.

You can still grab binaries even today using known npm cdns, for example like https://unpkg.com/browse/@swc/[email protected]/swc.exe without retrieve whole npm pkg.

[hochhaus]

Thanks for the tip @kwonoj. This would meet my needs perfectly.

Do you know why I'm receiving a 520 error when trying to fetch the linux binaries?

https://unpkg.com/browse/@swc/[email protected]/swc

[hochhaus]

It appears that I can access the binary via the URL without browse so this meets my needs. Many thanks.

https://unpkg.com/@swc/[email protected]/swc

[jirutka]

👍 This will also simplify adoption in linux distros – packaging swc. I’m working on Alpine Linux package right now.

[bandleader]

@kwonoj Minification does not seem to be working when using the native CLI. Tested with latest version 1.3.21 of @swc/core-win32-x64-msvc, using input from sdtin

# Node-based CLI -- minification works
node swc.js --filename input.ts --config minify=true --config sourceMaps=false
# Native CLI -- minification seems to be ignored
swc.exe compile --filename input.ts --config minify=true --config sourceMaps=false

[kwonoj]

#4017

[kwonoj]

--config is not implemented yet.

[bandleader]

Okay, so I guess I can use a config file then for now. Thank you!

[realtimetodie]

The --source-maps option was added in #6708.

[alexeagle]

FYI the latest release is good enough for Bazel (via https://github.com/aspect-build/rules_swc) to switch over to swcx thanks! Will be a big performance improvement since we spawn a subprocess for each file.