swc-node

library1.0.0jsnpmunverified

swc-node is a command-line interface (CLI) wrapper for `@swc-node/register`, a high-performance TypeScript and JavaScript transpiler designed for Node.js environments. While the `swc-node` package itself is at version `1.0.0` and has not seen recent updates (last published over four years ago), its core dependency, `@swc-node/register`, is actively developed, with its latest stable version being `1.11.0`. This library leverages SWC (Speedy Web Compiler), a Rust-based tool, to provide significantly faster compilation of TypeScript and modern JavaScript to a compatible target, often serving as a performant alternative to `ts-node` for development workflows. It focuses purely on transpilation without performing type checking, making it ideal for environments where build speed is prioritized and type checking is handled by a separate process (e.g., `tsc`). It supports both CommonJS via a `require` hook and ES Modules using Node.js's `--import` flag. Key differentiators include its Rust-native speed, minimal overhead, and `tsconfig.json` compatibility for transpilation options.

devops

npm install swc-node

package ↗

INSTALL

IMPORT

SIG · SWC-NODE

swc-node

devopsjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CommonJS Register Hook

✓ node -r @swc-node/register your-script.ts

✗ require('@swc-node/register'); // While technically correct, runtime registration via CLI flag is primary.

This registers the CommonJS require hook for on-the-fly TypeScript/JavaScript transpilation. Ensure `@swc-node/register` is installed as a dependency.

ES Modules Register Hook

✓ node --import @swc-node/register/esm-register your-module.ts

✗ node -r @swc-node/register/esm-register your-module.ts // -r is for CJS, --import for ESM

Registers the ES Module loader hook. Requires Node.js >= 12.17 for `--experimental-loader` or Node.js >= 20.6 for `--import` without `--experimental-loader`. Ensure `type: 'module'` in `package.json` for ESM projects.

CLI Execution

✓ npx swc-node your-script.ts

✗ node your-script.ts // Without transpilation, Node.js can't directly run TypeScript

The `swc-node` package itself provides a CLI executable for convenience, wrapping the `@swc-node/register` functionality. This is the primary advertised usage of the `swc-node` package.

This quickstart demonstrates how to set up a basic TypeScript project and run it using the `swc-node` CLI, as well as directly via the `@swc-node/register` CommonJS and ES Module runtime hooks.

{ "name": "my-swc-project", "version": "1.0.0", "description": "A simple SWC project demonstrating swc-node usage", "main": "src/index.ts", "type": "module", "scripts": { "start": "npx swc-node src/index.ts", "start-cjs": "node -r @swc-node/register src/index.ts", "start-esm": "node --import @swc-node/register/esm-register src/index.ts" }, "devDependencies": { "swc-node": "^1.0.0", "@swc-node/register": "^1.11.0", "typescript": "^5.0.0" } } // tsconfig.json { "compilerOptions": { "target": "es2020", "module": "esnext", "lib": ["es2020", "dom"], "strict": true, "esModuleInterop": true, "isolatedModules": true, "forceConsistentCasingInFileNames": true, "skipLibCheck": true }, "include": ["src/**/*.ts"] } // src/index.ts import { greet } from './util.js'; // Note .js extension for ESM resolution console.log(greet('Developer')); async function simulateAsyncCall() { console.log('Starting async operation...'); await new Promise(resolve => setTimeout(resolve, 1000)); console.log('Async operation complete!'); } simulateAsyncCall(); // src/util.ts export function greet(name: string): string { return `Hello, ${name}! This message was transpiled by SWC.`; }

swc-node --version

Debug

Known issues

deprecatedThe `swc-node` CLI package (version 1.0.0, last published over 4 years ago) is largely unmaintained. For the latest features, bug fixes, and better compatibility with modern Node.js and TypeScript versions, it is highly recommended to directly use the `@swc-node/register` package.

fix

Migrate to using `node -r @swc-node/register` for CommonJS or `node --import @swc-node/register/esm-register` for ES Modules, along with `@swc-node/register` as a direct dependency.

affects: >=1.0.0

gotchaSWC, and by extension `@swc-node/register`, performs *only* transpilation, not type checking. This means it will transform TypeScript code to JavaScript without validating types. Runtime errors due to type mismatches might occur if not caught by a separate `tsc --noEmit` step or IDE.

fix

Always run `tsc --noEmit` or integrate TypeScript's own type checker into your CI/CD pipeline or development workflow to ensure type safety, in addition to using SWC for fast transpilation.

affects: >=1.0.0

gotchaPlatform-specific `@swc/core` binaries are required. Issues can arise from Node.js architecture mismatches (32-bit vs. 64-bit), missing system dependencies (e.g., Microsoft Visual C++ Redistributables on Windows), or package manager issues with optional dependencies.

fix

Ensure your Node.js installation matches your operating system's architecture. On Windows, install the latest Microsoft Visual C++ Redistributables. If using `npm`, update it to the latest version and regenerate lockfiles to ensure optional dependencies are correctly installed.

affects: >=1.0.0

gotchaConfiguring decorators (e.g., `@Controller`) requires specific settings in `.swcrc` (e.g., `jsc.parser.decorators: true`) and/or `tsconfig.json` (e.g., `experimentalDecorators`, `emitDecoratorMetadata`, `useDefineForClassFields`). Incorrect configuration can lead to runtime errors or unexpected transpilation behavior.

fix

Carefully review SWC's documentation on decorators and `tsconfig.json` compatibility. Ensure `isolatedModules: true` and potentially `verbatimModuleSyntax: true` are set in `tsconfig.json` to flag code that might not transpile correctly without type-system awareness.

affects: >=1.0.0

gotchaES Module resolution and path aliases can be complex. Issues like `ERR_UNKNOWN_FILE_EXTENSION` or failure to resolve relative imports may occur when using `--import @swc-node/register/esm-register`, especially with older Node.js versions or specific testing frameworks like Mocha.

fix

Ensure `package.json` contains `"type": "module"` for ESM projects. Use explicit file extensions (e.g., `.js` in import paths for compiled output) and verify Node.js version compatibility with ESM features. Update `@swc-node/register` to the latest version, as ESM-related fixes are ongoing.

affects: >=1.0.0

Errors

Common errors & fixes

Failed to load SWC binary for {platform}/{arch} (Bindings not found)

SWC relies on native Rust binaries; this error indicates a failure to locate or load the correct binary for your system's architecture or operating system, often due to Node.js version/architecture mismatch or missing C++ runtime libraries on Windows.

fix

Verify your Node.js installation (e.g., `node -p "process.arch"`) matches your OS architecture. On Windows, install the Microsoft Visual C++ Redistributables. If using npm, try `npm cache clean --force` then `rm -rf node_modules package-lock.json` and `npm install` again to force a fresh download of optional platform-specific binaries.

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for {file_path}

This typically occurs in ES Module contexts when Node.js encounters a `.ts` file without a registered loader, or when the ESM loader for `@swc-node/register` isn't correctly configured or loaded.

fix

Ensure your `package.json` has `"type": "module"`. Use the command `node --import @swc-node/register/esm-register your-script.ts`. If using a test runner, verify its configuration for ESM and the SWC register hook. Update `@swc-node/register` to its latest version.

error: Unexpected token Some(At) --> {file_path}:{line}:{column} | {line} | @DecoratorName

SWC's parser did not recognize a decorator, usually because decorator support is not enabled in the SWC configuration (typically in a `.swcrc` file or via options passed to `@swc-node/register`).

fix

In your `.swcrc` configuration (or `jsc` options), ensure `jsc.parser.syntax` is `"typescript"` and `jsc.parser.decorators` is `true`. If using legacy decorators, also set `jsc.transform.legacyDecorator: true`. Also, verify `experimentalDecorators` and `emitDecoratorMetadata` are set in `tsconfig.json` if applicable.

Error: Cannot find module '@swc-node/register'

The `@swc-node/register` package is not installed as a dependency in your project, or Node.js cannot resolve its path.

fix

Run `npm install @swc-node/register` or `yarn add @swc-node/register` to add it to your `devDependencies`. Ensure your `node -r` or `node --import` command correctly references the installed package.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

@swc-node/registerrequiredProvides the core runtime transpilation functionality that swc-node wraps. This dependency is actively maintained, unlike the swc-node CLI itself.

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/swc-node ↗