esmon

2.0.1 verified Fri May 01 auth: no javascript

A fast file-watching runner and build tool for scripts, powered by esbuild. Version 2.0.1 uses esbuild for rapid compilation and restarting, with automatic dependency tracking, external module exclusion, and optional ESM output. It supports TypeScript decorators via swc and runs multiple commands (watch, run, build). Maintained by egoist, with regular updates. Differentiators: leverages esbuild's speed, built-in build command, and automatic watch of imported files.

Common errors

error Error: Cannot find module 'esbuild' ↓

cause esbuild is not installed or not in node_modules.

fix

Run 'npm install esbuild' or add it as a dependency.

error Command not found: esmon ↓

cause esmon is not installed globally or locally.

fix

Run 'npm install -D esmon' in your project directory.

error TypeError: __dirname is not defined ↓

cause Using CommonJS __dirname in ESM output.

fix

Use --esm flag or import.meta.url for ESM.

error Error: Decorator metadata not supported ↓

cause emitDecoratorMetadata not enabled in tsconfig.json.

fix

Set 'emitDecoratorMetadata': true in tsconfig.json compilerOptions.

error Build failed: Unexpected token ↓

cause Incompatible JavaScript/TypeScript syntax with esbuild.

fix

Ensure your code uses supported syntax; update esbuild version.

Warnings

gotcha Temporary files are emitted to ./temp folder; add to .gitignore. ↓

fix Add 'temp/' to your .gitignore file.

gotcha Default command watches files; use 'run' to execute once. ↓

fix Run 'esmon run your-script.ts' instead of 'esmon your-script.ts'.

gotcha ESM output uses --esm flag, not --format esm. ↓

fix Use 'esmon build --esm your-script.ts'.

gotcha Decorators require emitDecoratorMetadata in tsconfig.json; uses swc. ↓

fix Enable emitDecoratorMetadata in tsconfig.json.

gotcha devDependencies excluded by default; use --bundleDevDeps to include. ↓

fix Pass --bundleDevDeps flag to include devDependencies in bundle.

Install

npm install esmon

yarn add esmon

pnpm add esmon

Imports

esmon (CLI)
wrong
```
npm start esmon your-script.ts
```
correct
```
npx esmon your-script.ts
```
esmon is primarily a CLI tool, not a library.
run
wrong
```
esmon your-script.ts (without run flag runs watch mode)
```
correct
```
esmon run your-script.ts
```
The default command is watch; use 'run' to execute without watching.

build

wrong

esmon build your-script.ts --format esm (flag is --esm)

correct

esmon build your-script.ts

Use --esm for ESM output, not --format esm.

Quickstart

Install esmon as a dev dependency and run a TypeScript script with file watching.

npm i -D esmon
esmon your-script.ts