or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

code-compilation.md configuration-management.md esm-loader-support.md index.md runtime-registration.md

tile.json

Runtime Registration

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

Capabilities

Register Function

Registers transformation hooks for Node.js require() calls, enabling automatic TypeScript/JavaScript transformation with SWC.

/**
 * Registers transformation hooks for CommonJS modules
 * @param options - TypeScript compiler options (optional, defaults to reading from tsconfig.json)
 * @param hookOpts - Hook configuration options passed to pirates library
 * @returns Function to remove the transformation hooks
 */
function register(
  options?: Partial<ts.CompilerOptions>,
  hookOpts?: object
): () => void;

Usage Examples:

// Auto-registration using tsconfig.json
const { register } = require("@swc-node/register/register");
const removeHook = register();

// With custom compiler options
const removeHook = register({
  target: ts.ScriptTarget.ES2020,
  module: ts.ModuleKind.CommonJS,
  jsx: ts.JsxEmit.React,
  experimentalDecorators: true,
  emitDecoratorMetadata: true
});

// With hook options
const removeHook = register({}, {
  exts: ['.ts', '.tsx', '.js', '.jsx'],
  ignoreNodeModules: true
});

// Clean up when done
removeHook();

Auto-Registration Entry Point

The main package entry point that automatically calls register() with default options.

// Import automatically registers the hooks
require("@swc-node/register");

Usage Examples:

# CLI usage - automatically registers hooks
node -r @swc-node/register index.ts

# In package.json scripts
{
  "scripts": {
    "dev": "node -r @swc-node/register src/app.ts"
  }
}

Environment Variable Configuration

The registration process respects several environment variables for configuration:

SWC_NODE_PROJECT: Path to tsconfig.json file (takes precedence over TS_NODE_PROJECT)
TS_NODE_PROJECT: Path to tsconfig.json file
SWCRC: When set to truthy value, uses .swcrc file for SWC configuration
SWC_CONFIG_FILE: Path to SWC config file (used when SWCRC is set)
SWC_NODE_INLINE_SOURCE_MAP: Enable inline source maps
SWC_NODE_IGNORE_DYNAMIC: Ignore dynamic imports during transformation

Usage Examples:

# Use specific tsconfig.json
SWC_NODE_PROJECT=./tsconfig.dev.json node -r @swc-node/register app.ts

# Use .swcrc configuration
SWCRC=true node -r @swc-node/register app.ts

# Enable inline source maps
SWC_NODE_INLINE_SOURCE_MAP=true node -r @swc-node/register app.ts

Testing Framework Integration

Mocha:

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

AVA (package.json):

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

Jest (jest.config.js):

module.exports = {
  transform: {
    "^.+\\.(t|j)sx?$": "@swc-node/register"
  }
};

File Extension Support

The register function automatically handles these file extensions:

.js - JavaScript files
.ts - TypeScript files
.jsx - JavaScript with JSX
.tsx - TypeScript with JSX
.mjs - ES Module JavaScript
.mts - ES Module TypeScript
.cjs - CommonJS JavaScript
.cts - CommonJS TypeScript
.es6 - ES6 JavaScript
.es - ECMAScript files

All files with these extensions will be automatically transformed when required/imported.

Version

Tile

Files