{"id":12108,"library":"swc-node","title":"SWC Node.js CLI","description":"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.","status":"abandoned","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install swc-node","lang":"bash","label":"npm"},{"cmd":"yarn add swc-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add swc-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core runtime transpilation functionality that swc-node wraps. This dependency is actively maintained, unlike the swc-node CLI itself.","package":"@swc-node/register","optional":false}],"imports":[{"note":"This registers the CommonJS require hook for on-the-fly TypeScript/JavaScript transpilation. Ensure `@swc-node/register` is installed as a dependency.","wrong":"require('@swc-node/register'); // While technically correct, runtime registration via CLI flag is primary.","symbol":"CommonJS Register Hook","correct":"node -r @swc-node/register your-script.ts"},{"note":"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.","wrong":"node -r @swc-node/register/esm-register your-module.ts // -r is for CJS, --import for ESM","symbol":"ES Modules Register Hook","correct":"node --import @swc-node/register/esm-register your-module.ts"},{"note":"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.","wrong":"node your-script.ts // Without transpilation, Node.js can't directly run TypeScript","symbol":"CLI Execution","correct":"npx swc-node your-script.ts"}],"quickstart":{"code":"{\n  \"name\": \"my-swc-project\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A simple SWC project demonstrating swc-node usage\",\n  \"main\": \"src/index.ts\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"start\": \"npx swc-node src/index.ts\",\n    \"start-cjs\": \"node -r @swc-node/register src/index.ts\",\n    \"start-esm\": \"node --import @swc-node/register/esm-register src/index.ts\"\n  },\n  \"devDependencies\": {\n    \"swc-node\": \"^1.0.0\",\n    \"@swc-node/register\": \"^1.11.0\",\n    \"typescript\": \"^5.0.0\"\n  }\n}\n\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"target\": \"es2020\",\n    \"module\": \"esnext\",\n    \"lib\": [\"es2020\", \"dom\"],\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"isolatedModules\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"skipLibCheck\": true\n  },\n  \"include\": [\"src/**/*.ts\"]\n}\n\n// src/index.ts\nimport { greet } from './util.js'; // Note .js extension for ESM resolution\n\nconsole.log(greet('Developer'));\n\nasync function simulateAsyncCall() {\n  console.log('Starting async operation...');\n  await new Promise(resolve => setTimeout(resolve, 1000));\n  console.log('Async operation complete!');\n}\n\nsimulateAsyncCall();\n\n// src/util.ts\nexport function greet(name: string): string {\n  return `Hello, ${name}! This message was transpiled by SWC.`;\n}\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=1.0.0"},{"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.","message":"SWC, 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Platform-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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Configuring 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"ES 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Failed to load SWC binary for {platform}/{arch} (Bindings not found)"},{"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.","cause":"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.","error":"TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension \".ts\" for {file_path}"},{"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.","cause":"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`).","error":"error: Unexpected token Some(At) --> {file_path}:{line}:{column} | {line} | @DecoratorName"},{"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.","cause":"The `@swc-node/register` package is not installed as a dependency in your project, or Node.js cannot resolve its path.","error":"Error: Cannot find module '@swc-node/register'"}],"ecosystem":"npm"}