@swc-node/cli

@swc-node/cli is a tiny Node-first CLI powered by @swc-node/register.

Features

• TypeScript in both CommonJS and ESM projects.
• Hybrid module graphs (CJS importing ESM and ESM importing CJS).
• compilerOptions.paths / baseUrl path alias resolution from tsconfig.
• Node watch mode support (--watch, --watch-path, --watch-preserve-output).
• Node test runner support (--test).
• Decorator metadata support via tsconfig (experimentalDecorators + emitDecoratorMetadata).
• No extra swc dependencies required.

Usage

CLI

swc-node index.ts
swc-node --env-file=.env src/index.ts --port=3000

Inline code (-e / -p)

swc-node -e "const n: number = 1; console.log(n + 1)"
swc-node -p "const n: number = 41; n + 1"

Node test runner

swc-node --test ./math.test.ts

Without an explicit path, swc-node --test uses Node's default test discovery patterns, including TypeScript variants like:

**/*.test.?[cm][jt]s
**/*-test.?[cm][jt]s
**/*_test.?[cm][jt]s
**/test-*.?[cm][jt]s
**/test.?[cm][jt]s
**/test/**/*.?[cm][jt]s

Shebang scripts

For portable scripts, prefer putting options in tsconfig.json and keeping the shebang minimal:

#!/usr/bin/env swc-node

console.log('Hello, world!')

Then run the script directly:

./script.ts

CLI helpers

swc-node --help
swc-node --version

Read tsconfig.json

Set SWC_NODE_PROJECT via CLI flag:

swc-node --tsconfig ./tsconfig.dev.json src/index.ts
swc-node --tsconfig ./tsconfig.dev.json -e "console.log('hello')"

or via environment variable:

SWC_NODE_PROJECT=./tsconfig.dev.json swc-node src/index.ts

swc-node also supports compilerOptions.paths/baseUrl path aliases from the selected tsconfig.

swc-node --tsconfig ./tsconfig.dev.json src/index.ts
# imports like `@utils/foo` resolve from tsconfig paths

Need lower-level APIs?

If you need a programmable API or direct preload hooks (-r / --import), use @swc-node/register.

Notes

• Watch mode is delegated to Node (--watch) rather than custom orchestration.
• Running swc-node without an entrypoint is blocked (REPL mode is not supported).
• If you need a richer REPL/workflow tool, use tsx.

Thanks

Thanks to these projects for reference and preceding work:

• swrun
• swcx
• swc-node
• oxc-node
• tsx
• ts-node