@swc-node/register

What is @swc-node/register?

@swc-node/register is an npm package that allows you to use SWC (a super-fast TypeScript/JavaScript compiler) to transpile your code on-the-fly when running Node.js applications. This package is particularly useful for developers who want to leverage the speed of SWC for TypeScript or modern JavaScript features without needing to precompile their code.

What are @swc-node/register's main functionalities?

On-the-fly TypeScript Compilation

This feature allows you to run TypeScript code directly in Node.js without precompiling it. The code sample demonstrates how to require the @swc-node/register package and run TypeScript code on-the-fly.

require('@swc-node/register');
const tsCode = `const greet = (name: string): string => `Hello, ${name}`;`;
console.log(greet('World'));

Modern JavaScript Syntax Support

This feature allows you to use modern JavaScript syntax (like ES6 arrow functions) in Node.js applications. The code sample shows how to require the @swc-node/register package and run modern JavaScript code on-the-fly.

require('@swc-node/register');
const es6Code = `const add = (a, b) => a + b; console.log(add(2, 3));`;
eval(es6Code);

Configuration Options

This feature allows you to customize the SWC compiler options. The code sample demonstrates how to pass configuration options to the @swc-node/register package to set the JavaScript target version.

require('@swc-node/register')({
  swc: {
    jsc: {
      target: 'es2017'
    }
  }
});
const code = `const x = async () => await Promise.resolve('done'); x().then(console.log);`;
eval(code);

Other packages similar to @swc-node/register

ts-node

ts-node is a TypeScript execution environment for Node.js. It allows you to run TypeScript code directly without precompiling. Compared to @swc-node/register, ts-node is slower because it uses the TypeScript compiler (tsc) instead of SWC.

babel-register

babel-register is a package that hooks into Node.js require to compile files on the fly using Babel. It supports a wide range of JavaScript syntax and features. Compared to @swc-node/register, babel-register is slower because Babel is not as fast as SWC.

esbuild-register

esbuild-register is a package that allows you to use esbuild to compile JavaScript and TypeScript code on-the-fly in Node.js. It is similar to @swc-node/register in terms of speed, as esbuild is also a very fast compiler.

README

@swc-node/register

Usage

const register = require('@swc-node/register')

register({
  ...
})

CLI

node -r @swc-node/register index.ts

Mocha

mocha --require @swc-node/register --watch-extensions ts,tsx "test/**/*.{ts,tsx}" [...args]

ava

// package.json

{
  "ava": {
    "extensions": ["ts", "tsx"],
    "require": ["@swc-node/register"],
    "files": ["packages/**/*.spec.{ts,tsx}"]
  }
}

Read tsconfig.json

set SWC_NODE_PROJECT or TS_NODE_PROJECT env:

SWC_NODE_PROJECT=./tsconfig.test.json mocha --require @swc-node/register --watch-extensions ts,tsx "test/**/*.{ts,tsx}" [...args]

@swc-node/register respect the following option in tsconfig:

extends

@swc-node/register respect the extends key in tsconfig.json, and use the merged values.

compilerOptions.target

switch (target) {
  case ts.ScriptTarget.ES3:
    return 'es3'
  case ts.ScriptTarget.ES5:
    return 'es5'
  case ts.ScriptTarget.ES2015:
    return 'es2015'
  case ts.ScriptTarget.ES2016:
    return 'es2016'
  case ts.ScriptTarget.ES2017:
    return 'es2017'
  case ts.ScriptTarget.ES2018:
    return 'es2018'
  case ts.ScriptTarget.ES2019:
    return 'es2019'
  case ts.ScriptTarget.ES2020:
  case ts.ScriptTarget.ESNext:
  case ts.ScriptTarget.Latest:
    return 'es2020'
  case ts.ScriptTarget.JSON:
    return 'es5'
}

compilerOptions.jsx

If filename endsWith .jsx or .tsx, always set the jsx: true in swc config regards the jsx option in tsconfig. If filename not endsWith .jsx or .tsx, set the jsx: Boolean(tsconfig.compilerOptions.jsx) in swc config.

compilerOptions.module

notes, if compilerOptions.module higher than es2020, the dynamicImport in swc config will be set to true.

switch (moduleKind) {
  case ts.ModuleKind.CommonJS:
    return 'commonjs'
  case ts.ModuleKind.UMD:
    return 'umd'
  case ts.ModuleKind.AMD:
    return 'amd'
  case ts.ModuleKind.ES2015:
  case ts.ModuleKind.ES2020:
  case ts.ModuleKind.ESNext:
  case ts.ModuleKind.None:
    return 'es6'
  case ts.ModuleKind.System:
    throw new TypeError('Do not support system kind module')
}

compilerOptions.experimentalDecorators

Respect the boolean value in tsconfig.

compilerOptions.emitDecoratorMetadata

Respect the boolean value in tsconfig.

compilerOptions.esModuleInterop

Respect the boolean value in tsconfig.

include/exclude

TypeScript gives files list to @swc-node/register, if parse tsconfig.json failed or files list empty, @swc-node/register will transform all files which were required.

And if failed to parse tsconfig.json, @swc-node/register will print warning which contains failed reason.