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}
- 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
orimport
. - Efficient Build System: Uses
sucrase
to transpile TypeScript to JavaScript and performs fast AST manipulations for optimal interop.
- 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
oresbuild-runner
becausexnr
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.
- Local Development: Quickly run TypeScript scripts for development purposes without setting up a full build pipeline.
- CI/CD Pipelines: Use
xnr
in CI environments to run scripts or tests without needing to install heavy dependencies or run long build processes. - Utility Scripts: Ideal for writing and running small utility scripts for tasks like linting, formatting, or automating project workflows.
While you can use xnr
directly with npx
, you can also install it for frequent use:
npm install --save-dev xnr
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"
}
}
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"
}
}
- 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 butrequire(someVar)
will not) - Node.js Environment: Requires Node.js LTS version 16 or higher (for full ES module support).
- No Type Checking: Skips TypeScript type checking to speed up execution. If type checking is needed, consider running TypeScript directly.
CLI docs can be viewed at any time by running xnr --help
.
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)
runner | npx single-ts-file | (preinstalled) | install size |
---|---|---|---|
xnr@2.0.0 | 0.7 sec |
0.3 sec |
0.4 MB |
xnr@1.1.4 | 0.8 sec |
0.3 sec |
6.7 MB |
ts-node | 0.9 sec |
0.8 sec |
6.7 MB |
esr | 1.8 sec |
0.4 sec |
29.9 MB |
tsx | 4.9 sec |
0.3 sec |
29.7 MB |
swc-node | 5.4 sec |
0.2 sec |
62.0 MB |
In general you can expect best-in-class install + run time.
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.
Apache-2.0