Home

Awesome

:zap: Esbuild Runner (esr)

Super-fast on-the-fly transpilation of modern JS, TypeScript and JSX using esbuild.

esr makes it easy to run arbitrary code or tests without needing to build your whole project. It's a great way to improve your development workflow.

✨ Usage

The easiest way to use esbuild-runner is to install it globally and use the included esr binary.

$ esr hello-world.ts

Alternatively, you can require esbuild-runner within any nodejs process to include realtime transpilation:

$ node -r esbuild-runner/register hello-world.ts

In order to use esbuild-runner with Jest, you need to configure a Jest transform in your jest.config.js

module.exports = {
  transform: {
    "\\.ts$": "esbuild-runner/jest",
  },
}

VSCode Debugging

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with esbuild-runner",
      "program": "${workspaceFolder}/hello-world.ts",
      "runtimeArgs": [
        "-r",
        "esbuild-runner/register"
      ],
      "request": "launch",
      "sourceMaps": true,
      "skipFiles": [
        "<node_internals>/**"
      ],
      "type": "pwa-node"
    }
  ]
}

⚙️ Configuration

esr provides two different ways to transpile your code:

$ bin/esr.js --help
Usage: esr [options] <source-file> [file-options]

  --cache       Transform on a file per file basis and cache code
  --clearCache  Clear transform cache
  --help|-h     Display this help message

To customize the options passed to esbuild, you can create an esbuild-runner.config.js file in the current directory or one of the ancestor directories.

// example esbuild-runner.config.js
module.exports = {
  type: "bundle", // bundle or transform (see description above)
  esbuild: {
    // Any esbuild build or transform options go here
    target: "esnext",
  },
}

📦 Installation

Simply install the esbuild-runner npm package using your favorite package manager.

$ npm install -g esbuild-runner
$ npm add --dev esbuild-runner

👋 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

⚖ License

Apache 2.0

<!-- markdownlint-disable-file MD014 MD033 -->