esrun

3.2.30 verified Fri May 01 auth: no javascript deprecated

esrun is a lightweight CLI tool that executes TypeScript and modern JavaScript files directly using esbuild for near-instant compilation, without requiring a bundler. It supports custom tsconfig, top-level await, and watch mode for re-executing on file changes. It handles both CJS and ESM dependencies seamlessly. However, the package is deprecated as of version 3.2.30 (current stable). Maintainers recommend migrating to Bun or, for Node.js compatibility, tsx. Last useful release: 3.2.30, minimal maintenance since. Designed for quick demonstrations and test execution, it differentiates itself by zero-config setup and esbuild's speed, but is now superseded.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/esrun not supported. ↓

cause Using CommonJS require() with ESM-only esrun v3.

fix

Change to dynamic import: const esrun = await import('esrun'); or switch to ESM.

error ReferenceError: exports is not defined in ES module scope ↓

cause Mixing import/export with CommonJS module.exports in the executed file.

fix

Use consistent ESM syntax: export/import, not module.exports/require.

error Could not resolve: /path/to/tsconfig.json (tsconfig not found) ↓

cause Invalid path provided to --tsconfig parameter.

fix

Use absolute path or relative path from current working directory.

Warnings

deprecated This package is deprecated. Use Bun or tsx instead. ↓

fix Migrate to Bun (bun run file.ts) or tsx (npx tsx file.ts).

breaking v3 dropped CommonJS support. require() will throw. ↓

fix Use ESM imports (import) or use an older v2.x if absolutely required.

gotcha Watch mode flag --watch must be placed before the file path, otherwise it's passed as an argument to the script. ↓

fix Correct: esrun --watch foo.ts. Wrong: esrun foo.ts --watch.

gotcha Top-level await requires module setting in tsconfig: "module": "esnext". ↓

fix Set "compilerOptions": { "module": "esnext" } in tsconfig.json.

deprecated Use of --tsconfig parameter may be removed in future versions. ↓

fix Pass tsconfig via esrun --tsconfig=/path (still supported, but not guaranteed).

Install

npm install esrun

yarn add esrun

pnpm add esrun

Imports

default
wrong
```
const esrun = require('esrun')
```
correct
```
import esrun from 'esrun'
```
The package is ESM-only from v3; CommonJS require will throw.

run

wrong

const { run } = require('esrun')

correct

import { run } from 'esrun'

Named export 'run' available only via ESM import.

types (TypeScript)
wrong
```
import { Options } from 'esrun' (value import)
```
correct
```
import type { Options } from 'esrun'
```
Types are exported, but using them as values will cause runtime errors.

Quickstart

Shows a minimal TypeScript file with an async import, executed via esrun CLI.

// 1. Install globally or locally
// npm i -g esrun

// 2. Create a TypeScript file: hello.ts
// content:
import { run } from 'esrun';
import { greet } from './greet';

async function main() {
  const message = await greet('World');
  console.log(message);
}

// greet.ts 
export async function greet(name: string): Promise<string> {
  return `Hello, ${name}!`;
}

// 3. Execute: esrun hello.ts