esdev build

esdev build server.ts                          # → dist/server.js
esdev build src/app.ts --out=dist/app.js --minify

One entry, one file, ES modules out. runtime:* imports are left for the runtime to serve, and CommonJS dependencies are converted on the way in.

The CommonJS answer

esrun runs ES modules only, and a large share of npm — React included — still ships CommonJS. There were two ways out: teach the runtime require, or convert on the developer's machine.

Teaching the runtime require would break the property that a deployed artifact is the text that was reviewed. So the bundler absorbs CJS→ESM at build time and esrun receives ordinary ESM. The non-goal holds completely rather than being narrowed:

esdev build server.js         # a CJS dependency goes in
esrun dist/server.js          # ordinary ESM comes out

It also shortens the deploy line

An unbundled program needs --allow-imports, because the loader walks node_modules at runtime. A bundle has no imports left to resolve:

esrun --allow-imports --allow-listen=8080 app.js  # unbundled
esrun --allow-listen=8080 dist/app.js             # bundled

The build is a security step, not only a packaging one.

Options

What it gets right for you

Four settings are the actual product, and each is silent when wrong — which is why this is a command rather than documentation telling you to run a bundler.

--conditions adds rather than replaces, so asking for one more cannot silently cost you worker. The runtime's condition set stays standards-only; the escape hatch belongs to the bundler, where you chose to run it, not to a server resolving imports under load.

A dynamic import() emits a chunk beside the entry, content-hashed. That is what outdir below is for.

A project: esdev.json

A command line describes one bundle. An app that renders on the server and hydrates in the browser is two, from two entries, with two shapes of output — and the site it prerenders is a third that has to run.

{
  "targets": {
    "server":    { "entry": "src/server.ts", "out": "dist/server.js",
                   "assets": ["index.html", "public"] },
    "browser":   { "entry": "src/entry.client.tsx", "outdir": "dist/client",
                   "platform": "browser" },
    "prerender": { "entry": "src/prerender.ts", "out": "dist/prerender.js",
                   "then": "run" }
  }
}

esdev build                      # every target
esdev build --target=browser     # one
esdev build src/app.ts           # ignores the file entirely

define values keep the JSON type you wrote: "MODE": "dev" replaces with a string, "PORT": 8080 with a number. A flag beats the file, so --minify takes a release build of a project whose day to day is unminified.

The three shapes

then: "run" is how a static site is generated without esdev knowing what one is: the bundle runs, and what it writes is the output. It runs in a child process, after every target is built.

Assets and the deployment

A relative path resolves against the entry module's directory, so a server bundle in dist/ reading index.html reads dist/index.html. Assets are copied there by the build, which is what makes dist/ the whole deployment — a directory copied by its contents, so public/styles.css is served at /styles.css with nothing rewriting an href.

An HTML entry

A server bundle starts at a module, because the runtime does. The browser starts at a document.

{ "targets": { "web": { "entry": "index.html", "outdir": "dist" } } }

The tags in it are the build's inputs:

<link rel="stylesheet" href="./styles.css" />
<script type="module" src="./src/entry.client.tsx"></script>

become, in dist/index.html:

<link rel="stylesheet" href="/assets/styles-621d3b66.css" />
<script type="module" src="/assets/entry.client-fccaa347.js" />

A relative path is an input. A rooted path (/assets/vendor.js), a URL and a data: URI are left exactly as written — the escape hatch for anything the build should keep out of.

Dynamic import() chunks land in the same directory, hashed by the bundler, and the entry still points at them.

A <link rel="stylesheet"> is an entry too. It and everything it @imports become one hashed file, and a relative url() is followed, so fonts and images travel with the stylesheet instead of arriving as 404s once it moves to /assets. --minify drops comments and collapses whitespace.

CSS Modules

A *.module.css imported from JavaScript is scoped to the file that declares it, and the import resolves to the mapping:

import styles from "./Button.module.css";  // { button: "button_a1b2c3d4" }

Class names, id selectors and @keyframes are renamed; the scoped name comes from the file's path, so a server build and a browser build agree without talking to each other. :global(…) opts out. Every module's CSS is collected into one hashed stylesheet and linked from the document — never injected from script, so nothing needs style-src 'unsafe-inline'.

composes reuses a class without repeating its rules — from the same file, from another module (composes: a from "./x.module.css"), or from outside the system (composes: a from global). The mapping's value becomes a list of class names, and it is transitive.

A .css that is not .module.css is emitted unscoped. That is what third-party stylesheets need: a library's own JavaScript emits its class names as hardcoded strings, so scoping them would break it.

Where the file is

./esdev.json, or --config=<path> — paths inside it resolve against the file, not the working directory.

End to end

React 19 streaming SSR behind Hono, from CommonJS packages, served by esrun with no filesystem or import access at all:

esdev build server.tsx --out=dist/server.js --minify
esrun --allow-listen=8080 dist/server.js

Libraries: --lib

esdev build --lib src            # src/** → dist/**.js + dist/**.d.ts

A library is an input to somebody else's build, so every default above is theirs to make and --lib makes none of them.

Skipped: *.test.* and .d.ts files. An --out that holds your source or your project is refused rather than emptied; an application build never cleans, since its --out is one file in a directory that may hold other things.

Declarations

Derived from what the source says, never from what a checker infers — the same contract type-stripping has. So an exported signature has to state its type:

export const driver = defineDriver({ … });                    // ✗
export const driver: Driver<Conn, Opts> = defineDriver({ … }); // ✓

A signature that does not fails the build with the list, rather than getting a guessed declaration nobody can see is wrong. TypeScript calls this rule isolatedDeclarations.

error: 2 declarations could not be derived:

  src/index.ts:150:14  TS9010: Variable must have an explicit type annotation.
  src/pool.ts:41:14    TS9010: Variable must have an explicit type annotation.

--no-types skips them.

One declaration file

A package whose exports map has a single entry wants one index.d.ts, not a mirror of a source layout nobody outside it should have to know:

esdev build --lib src --dts-bundle    # → dist/index.d.ts

Keep the per-module .d.ts if your exports map has subpaths — @you/pkg/pool has to find a real pool.d.ts.

A construct that cannot be linked into one file — a namespace import, export =, a module augmentation — stops the build and names itself. A .d.ts is believed: nothing runs it and no test covers it, so a wrong one is worse than none.

Options