esdev

Two binaries. esrun runs a service in production and has no development surface at all — no inspector port, no file watcher, no test discovery, no transform, and it grants nothing unless the command line says so. That narrowness is what makes --allow-listen=8080 a statement rather than a hope, and it bills your inner loop. esdev is the binary that pays it.

esdev create my-app           # scaffold a project that already runs
esdev start                   # the dev loop: build, run, rebuild, reload
esdev app.ts                  # TypeScript, JSX, run
esdev --watch server.ts       # rerun on change, drain on restart
esdev test                    # run the test files
esdev build server.ts         # one deployable ES module
esdev build --lib src         # a publishable library, with its .d.ts
esdev --inspect app.ts        # attach a debugger
esdev --trace-permissions app.ts   # print the esrun line to deploy with
esdev upgrade                 # update esdev to the latest release

It never changes what the JS sees

Same prelude, same snapshot, same providers, same capability enforcement — all shared with esrun, in one crate both binaries sit on. A program cannot behave one way here and another in production. What esdev changes is everything around a run: watching, restarting, attaching, discovering, reporting, building.

The permission flags are the same ones and mean the same thing, with one deliberate difference: esdev grants everything by default, esrun grants nothing. An inner loop should not need flags to run the program you are in the middle of writing; a deployment should say what it may reach. Everything else — the names, the scope lists, the rules, the error messages — is one implementation shared by both binaries.

esdev server.ts                              # everything granted
esdev --deny-all --allow-listen=8080 server.ts   # ...or exactly esrun's grant

esdev --trace-permissions server.ts closes the gap: it prints the esrun line that grants exactly what a run reached for. See Tracing permissions.

Get it

The installer places both binaries, and esdev updates itself from there:

curl -fsSL https://raw.githubusercontent.com/Open-Tech-Foundation/ES-Runtime/main/install.sh | bash
esdev upgrade                            # ...and later

esdev upgrade replaces the running binary with the newest esdev release for your platform — the same thing esrun upgrade does for the other one, and the same outcome as re-running the installer. Each resolves its own release: the two are versioned separately and tagged separately.

From source, which is the only way to get the debugger:

cargo build-dev                          # → target/release/esdev
ES_RUNTIME_INSPECTOR=1 cargo build-dev   # ...with the debugger

--inspect needs the second line — it is compiled in only when the build asks for it, and a build without it says so instead of listening on nothing.

TypeScript & JSX

esdev runs .ts, .tsx, .mts, .cts and .jsx directly by stripping types and compiling JSX; .js passes through untouched. Types are erased, not checked, and import specifiers stay exactly as written so development and production resolve the same modules.

See TypeScript setup for editor types and configuration.

Watch

For the standalone --watch command, see Watch mode. For a configured project that rebuilds and serves targets, see The dev loop.

Three modules only esdev serves

Development machinery is available to the program as well as to the command line — as runtime: modules that exist under esdev and nowhere else:

The first and last are here for the thing a subcommand cannot be: a framework's dev server, which bundles a route on demand, keeps the chunk in memory, serves it, and on a save drops exactly the chunks that used the changed file. The cache, the browser websocket and the route table belong to that program, so what it needs from this toolchain is an API rather than a command.

import { build } from "runtime:build";
import { watch } from "runtime:watch";

const bundle = await build({ input: route, plugins: [mdx()] });
const { output, watchFiles } = await bundle.generate({ codeSplitting: false });

esrun serves none of them: importing one there fails at load rather than half-working. See the bundler bridge for how a parallel bundler and a single-threaded isolate share the work.

Flags

Everything esrun takes, plus these. Every flag is --flag or --flag=value — a value is never a separate argument — and they come before the script.

Each subcommand takes --help, and every --help is short on purpose: the grammar and the flags, then a link to the page that has the rest.

What it deliberately is not

No formatter and no linter: oxlint and oxfmt are npm binaries that already work, and neither oxc_formatter nor oxc_linter is published as a usable library crate. No package installer — esrun resolves an existing node_modules and installs nothing, which is correct. No task runner. And no framework's dev server: esdev start is the build on a loop for the project in front of it, not an asset graph somebody else's router plugs into. What esdev offers instead is the bundler and the watcher as modules — so the framework that wants one can be a program on this runtime rather than a Node script.