esdev start

esdev start

It is esdev build on a loop. A dev build differs from a release build in three ways and no more: process.env.NODE_ENV is "development", nothing is content-hashed, and the browser bundle is built so a module can be replaced in place.

On a change: rebuild, restart the server if its bundle moved, and patch the page — or reload it if nothing accepted the change. Read the details in Hot module replacement.

The server is yours

"start": { "run": "server" }

That names the target whose output is your server. esdev runs it as a child process under the config's permissions and restarts it with a SIGTERM — the graceful stop production gets, so a request in flight when you save is answered rather than dropped.

It is the same file production runs. No dev server stands in for it, nothing wraps it, and there is no second code path that exists only on your machine.

A project with no server of its own — a static site or single-page app — has nothing to run, so esdev serves the output directory itself: files, an index.html fallback for client-side routes, and nothing else.

A failed build changes nothing

esdev: src/App.tsx: Unexpected token

The server you were about to fix is still running, still serving, and the browser is not told anything. The rebuild happens before anything is stopped, so the old server also answers during it.

The update channel

Every built document gets a WebSocket to ws://127.0.0.1:<port>/@esdev/hmr. It acts on a module patch, stylesheet swap, or reload. It is esdev's endpoint rather than your application's, so nothing dev-only reaches your source and the file you edit is never written to.

An update is sent after a restart finishes. The client reconnects on its own, backing off to a 5 s ceiling, because a restarted dev server is ordinary. The port is written into the document when it is built, so this works while the endpoint keeps the same port. If you stop and start esdev again and its unpinned endpoint chooses a different port, reload the page; the old document cannot discover that new endpoint. For a frontend project, use --port=<n> to pin the endpoint.

Options

"start": { "run": "server", "watch": ["server", "web"], "serve": "dist", "port": 8080 }

watch narrows what gets rebuilt; leaving it out rebuilds everything. serve overrides the directory served when there is no run.

What is watched

esdev start watches the project root, every explicitly scoped --allow-read path from esdev.json or the command line, and the build inputs those paths may contain. Target output directories are always excluded so a build cannot trigger itself. Rules in the project's root .gitignore also exclude matching paths; other directory names are not hardcoded exclusions.

That includes modules and the things a build consumes that a run does not: index.html, stylesheets, images and fonts. An explicit allowed path is both part of the child permission grant and the watch list. An unscoped --allow-read grants access but does not identify a finite directory to watch.

For the standalone command's narrower rules, see Watch mode.

Preview the release

Use Previewing a release after esdev build to check production-mode output, hashed URLs and the static server behavior.