xnr

Easily, quickly, and reliably run a TypeScript Node.js script from the CLI with zero configuration. Blazingly fast 🚀

npx xnr any-file.{ts,tsx,cts,mts,js,jsx,cjs,mjs}

Ideal for utility scripts, quick debugging and CI pipelines

Key Features

• Zero configuration: Run your TypeScript files directly without needing a tsconfig file or any additional setup. Ideal for quick scripts or CI tasks
• Supports multiple file types: Easily run any combination of TypeScript, JavaScript, JSON and JSX files
• Lightweight: Very quick to install at just ~400kB
• Flexible and familiar: Tolerant to different file extensions, but otherwise follows Node conventions
• Optimised for Speed: Faster install+execution time than xnr
• Focused Scope: Single goal: run TypeScript code quickly and reliably
• Supports Windows

Getting Started

Installation

While you can use xnr directly with npx, you can also install it for frequent use:

npm install --save-dev xnr

Running a Script

Simply use npx to run your TypeScript or JavaScript file:

npx xnr file.ts

For running dev scripts in your package.json:

{
  "scripts": {
    "run": "xnr run.ts"
  }
}

Caveats and Scope

• Only supports dynamic imports or requires with static strings (e.g. require("./file.ts") will work but require(someVar) will not)
• Requires Node.js 16.14 or higher (for full ES module support)

CLI

CLI docs can be viewed at any time by running xnr --help.

API

xnr also provides an API with a few more options than the CLI:

// Runs a file with auto-transpilation of it and its dependencies, as required.
const run: (filePathOrConfig: string | RunConfig) => Promise<number>;

// Converts all local source code starting from an entry file into a directly runnable directory of Node.js compatible code.
const build: ({
  filePath,
  outputDirectory,
}: {
  filePath: string;
  outputDirectory: string;
}) => Promise<Output>;

// Converts all local source code starting from an entry file into a runnable array of Node.js compatible file contents.
const transpile: ({ filePath }: { filePath: string }) => Promise<Output>;

// Transforms an input code string into a Node-friendly ECMAScript Module (ESM) code string. Unlike the others here, it doesn't rewrite imports.
const transform: ({ code, filePath }: { code: string; filePath?: string }) => Promise<string>;

A complete list of exports can be viewed on npmjs.com (navigate to /xnr/dist/lib/index.d.ts)

Jest transformer

Add these lines to your jest config to get easy TS transforms:

{
  // ...
  "extensionsToTreatAsEsm": [".ts"],
  "transform": {
    "\\.ts$": "<rootDir>/node_modules/xnr/dist/jest.js"
  }
  // ...
}

Key benchmarks

runner	run single file	run small project	install size	install time
xnr	93ms	102ms	0.4MB	very quick
tsx	142ms	146ms	29.7MB	slow
swc-node	232ms	235ms	62.0MB	very slow
ts-node	661ms	659ms	6.7MB	quick

In general, you can expect best-in-class install + run time.

Contributing

Feel free to open issues if you encounter bugs or have suggestions for new features.

Licence

Apache-2.0