What is esbuild-runner?
The esbuild-runner npm package is a tool that allows you to run JavaScript and TypeScript files using esbuild, a fast JavaScript bundler and minifier. It is designed to be a lightweight and efficient alternative to other build tools, providing quick startup times and minimal configuration.
What are esbuild-runner's main functionalities?
Running JavaScript files
This feature allows you to run JavaScript files directly using esbuild. The `register` function sets up the environment, and then you can require and run your JavaScript file.
const { register } = require('esbuild-runner');
register();
require('./your-script.js');
Running TypeScript files
This feature allows you to run TypeScript files directly using esbuild. Similar to running JavaScript files, the `register` function sets up the environment, and then you can require and run your TypeScript file.
const { register } = require('esbuild-runner');
register();
require('./your-script.ts');
Custom esbuild options
This feature allows you to customize esbuild options when running your scripts. You can specify options like the target environment, JSX factory, and JSX fragment.
const { register } = require('esbuild-runner');
register({
target: 'es2017',
jsxFactory: 'h',
jsxFragment: 'Fragment'
});
require('./your-script.tsx');
Other packages similar to esbuild-runner
ts-node
ts-node is a TypeScript execution environment and REPL for Node.js. It allows you to run TypeScript files directly without precompiling them. Compared to esbuild-runner, ts-node is more focused on TypeScript and provides a more integrated TypeScript experience, but it may not be as fast as esbuild-runner.
babel-node
babel-node is a CLI tool that comes with Babel, allowing you to run JavaScript and TypeScript files with Babel transformations applied. It is more flexible in terms of transformations and plugins compared to esbuild-runner, but it can be slower due to the additional overhead of Babel.
sucrase
Sucrase is a super-fast alternative to Babel for compiling modern JavaScript and TypeScript. It focuses on speed and simplicity, similar to esbuild-runner, but it has fewer features and less flexibility in terms of transformations.
: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:
- bundling (default): this transpiles the script and all its dependencies in typically one invocation of esbuild. Dependencies defined in
package.json
or node_modules
will never be transpiled. Running esr
will always transpile the code. No caching is used. - transform (
--cache
): this method will invoke esbuild for every source file, but will cache the result. This means that the initial run will be slower, but after that, only changed source files will be transpiled.
$ 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.
module.exports = {
type: "bundle",
esbuild: {
target: "esnext",
},
}
📦 Installation
Simply install the esbuild-runner npm package using your favorite package manager.
$ npm install -g esbuild-runner
- ... or locally in your project
$ 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