Skip to content

Latest commit

 

History

History
130 lines (93 loc) · 3.73 KB

README.md

File metadata and controls

130 lines (93 loc) · 3.73 KB
Raw

xnr

banner

npm npm type definitions license install size

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