or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

code-compilation.mdconfiguration-management.mdesm-loader-support.mdindex.mdruntime-registration.md
tile.json

tessl/npm-swc-node--register

SWC node register - A faster ts-node/register/transpile-only alternative that provides TypeScript/JavaScript transformation without compilation or typechecking for Node.js runtime registration hooks

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@swc-node/register@1.11.x

To install, run

npx @tessl/cli install tessl/npm-swc-node--register@1.11.0

index.mddocs/

SWC Node Register

SWC Node Register is a high-performance TypeScript/JavaScript transformer for Node.js that serves as a faster alternative to ts-node/register/transpile-only. It enables runtime transformation of TypeScript and JavaScript files without compilation or type checking, making it ideal for development environments where speed is prioritized over type safety.

Package Information

  • Package Name: @swc-node/register
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @swc-node/register

Core Imports

// Auto-registration (main entry point)
import "@swc-node/register";

// Programmatic registration and compilation
import { register, compile } from "@swc-node/register/register";
import { readDefaultTsConfig, tsCompilerOptionsToSwcConfig } from "@swc-node/register/read-default-tsconfig";

// ES Module loader support
import "@swc-node/register/esm-register";

For CommonJS:

// Auto-registration (main entry point)
require("@swc-node/register");

// Programmatic registration and compilation
const { register, compile } = require("@swc-node/register/register");
const { readDefaultTsConfig, tsCompilerOptionsToSwcConfig } = require("@swc-node/register/read-default-tsconfig");

Basic Usage

// Auto-registration (simplest approach)
require("@swc-node/register");

// Programmatic registration with options  
const { register } = require("@swc-node/register/register");
const ts = require("typescript");
const removeHook = register({
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS,
  jsx: ts.JsxEmit.React
});

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

// ES Module usage with Node.js loaders
// node --import @swc-node/register/esm-register --enable-source-maps script.ts

Architecture

SWC Node Register is built around several key components:

  • Registration Hooks: Integration with Node.js require system and ESM loader for automatic file transformation
  • SWC Integration: Uses SWC (Speedy Web Compiler) for high-performance transformation with TypeScript compiler API fallback
  • Configuration System: Reads and respects tsconfig.json settings while providing SWC-specific optimizations
  • Source Map Support: Maintains accurate debugging information through inline source maps
  • Module Resolution: Handles complex module resolution patterns including path mapping and different module formats

Capabilities

Auto-Registration Entry Point

The main package entry point that automatically registers transformation hooks using default tsconfig.json settings when imported or required.

// Import automatically registers hooks with default settings
import "@swc-node/register";

// Require automatically registers hooks with default settings
require("@swc-node/register");

Runtime Registration

Programmatic registration of transformation hooks for CommonJS modules with full tsconfig.json integration and environment variable configuration support.

function register(
  options?: Partial<ts.CompilerOptions>,
  hookOpts?: object
): () => void;

Runtime Registration

Code Compilation

Direct compilation of TypeScript/JavaScript code with SWC transformation and optional TypeScript compiler fallback for complex cases.

function compile(
  sourcecode: string | undefined,
  filename: string,
  options: ts.CompilerOptions & { fallbackToTs?: (filename: string) => boolean },
  async?: boolean
): string | undefined | Promise<string | undefined>;

Code Compilation

Configuration Management

TypeScript configuration reading, parsing, and conversion to SWC-compatible format with caching and environment variable support.

function readDefaultTsConfig(
  tsConfigPath?: string
): Partial<ts.CompilerOptions & { fallbackToTs: (path: string) => boolean }>;

function tsCompilerOptionsToSwcConfig(
  options: ts.CompilerOptions,
  filename: string
): Options;

Configuration Management

ESM Loader Support

Node.js ES Module loader hooks for module resolution and transformation with TypeScript path mapping and package type detection.

function resolve(
  specifier: string,
  context: object,
  nextResolve: Function
): Promise<ResolveFnOutput>;

function load(
  url: string,
  context: object,
  nextLoad: Function
): Promise<LoadFnOutput>;

function getPackageType(url: string): Promise<"module" | "commonjs" | undefined>;

ESM Loader Support

Common Types

// SWC transformation options (from @swc-node/core)
interface Options {
  target?: "es3" | "es5" | "es2015" | "es2016" | "es2017" | "es2018" | "es2019" | "es2020" | "es2021" | "es2022";
  module?: "commonjs" | "umd" | "amd" | "es6";
  jsx?: boolean;
  sourcemap?: boolean | "inline";
  experimentalDecorators?: boolean;
  emitDecoratorMetadata?: boolean;
  useDefineForClassFields?: boolean;
  esModuleInterop?: boolean;
  dynamicImport?: boolean;
  keepClassNames?: boolean;
  externalHelpers?: boolean;
  baseUrl?: string;
  paths?: Record<string, string[]>;
  ignoreDynamic?: boolean;
  react?: {
    pragma?: string;
    pragmaFrag?: string;
    importSource?: string;
    runtime?: "automatic" | "classic";
    useBuiltins?: boolean;
  };
  swc?: {
    sourceRoot?: string;
    inputSourceMap?: boolean;
  };
}

// Node.js ESM loader interfaces
interface ResolveFnOutput {
  url: string;
  format?: "builtin" | "commonjs" | "json" | "module" | "wasm";
  shortCircuit?: boolean;
}

interface LoadFnOutput {
  source: string | ArrayBuffer;
  format?: "builtin" | "commonjs" | "json" | "module" | "wasm";
  shortCircuit?: boolean;
}