xnr

Easily, quickly, and reliably run a Node.js script from the CLI with zero configuration. As fast and simple as tsx with a much faster install.

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

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.
• Fast Execution: Skips TypeScript type checking for instant execution.
• Lightweight: Including dependencies <7MB, ideal for CI pipelines.
• Flexible and Tolerant: Works well with different module systems and rogue npm dependencies that expect either require or import.
• Efficient Build System: Uses sucrase to transpile TypeScript to JavaScript and performs fast AST manipulations for optimal interop.

Why Choose xnr?

• Quick and Simple: Ideal for running TypeScript files without the overhead of setting up a complex build environment or configuration files.
• Better Interoperability: More seamless integration with different module systems compared to ts-node.
• Optimised for Speed: Faster install and execution times than swc or esbuild-runner because xnr doesn’t rely on compiled binaries from other languages.
• Focused Scope: Designed to reduce the hassle of running TypeScript in Node.js without overreaching into other tasks or environments.

Common Use Cases

1. Local Development: Quickly run TypeScript scripts for development purposes without setting up a full build pipeline.
2. CI/CD Pipelines: Use xnr in CI environments to run scripts or tests without needing to install heavy dependencies or run long build processes.
3. Utility Scripts: Ideal for writing and running small utility scripts for tasks like linting, formatting, or automating project workflows.

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"
  }
}

Building for Later Execution

You can also use this to pre-compile TS code for running on Node.

xnr build ./entry.ts ./dist/

For running build scripts in your package.json:

{
  "scripts": {
    "build": "xnr build entry.ts dist"
  }
}

Caveats and Scope

• Platform Support: Currently, xnr does not support Windows. Contributions to add Windows support are welcome!
• JSX/TSX Assumptions: Assumes JSX is React in .jsx and .tsx files. Other JSX targets may be supported in future versions.
• Dynamic Imports/Requires: Only supports dynamic imports or requires with static strings (e.g. require("./file.ts") will work but require(someVar) will not)
• Node.js Environment: Requires Node.js LTS version 16 or higher (for full ES module support).

Performance and Limitations

• No Type Checking: Skips TypeScript type checking to speed up execution. If type checking is needed, consider running TypeScript directly.

CLI

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

API

xnr also provides an API with the same options as the CLI.

// Runs a file, auto-transpiling it and its dependencies as required
export const run = async (
  filePathOrConfig: string | { filePath: string; args?: string[]; nodeArgs?: string[]; /* ... */  }
) => Promise<number>; // Exit Code

// Convert source code from an entry file into a directory of Node-friendly ESM code
export const build = ({ filePath: string, outputDirectory: string })
  => Promise<{ entrypoint: string; /* ... */ }>;

// Convert an input code string to a Node-friendly ESM code string
export const transform = ({ 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)

Key benchmarks

| runner | npx single-ts-file | (preinstalled) | install size | | --------- | -----------------: | -------------: | -----------: | | [email protected] | 0.7sec | 0.3sec | 0.4MB | | [email protected] | 0.8sec | 0.3sec | 6.7MB | | ts-node | 0.9sec | 0.8sec | 6.7MB | | esr | 1.8sec | 0.4sec | 29.9MB | | tsx | 4.9sec | 0.3sec | 29.7MB | | swc-node | 5.4sec | 0.2sec | 62.0MB |

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. Windows support and additional JSX framework compatibility are areas for potential contributions.

Licence

Apache-2.0