ui-tui: bundle with esbuild, drop runtime node_modules by ethernet8023 · Pull Request #18036 · NousResearch/hermes-agent

ethernet8023 · 2026-04-30T17:36:05Z

What does this PR do?

Replace the tsc + babel pipeline with a single esbuild invocation that produces a self-contained dist/entry.js. The nix TUI derivation no longer copies node_modules — only dist/ + package.json ship, shrinking the output from hundreds of MB to ~2.9 MB.
Also simplifies the TUI launcher: rips out the staleness-tracking maze (~100 LOC of mtime walks across source trees) in favor of three clear paths — prebuilt, dev, always-build. esbuild is fast enough (~1s) that caching the build was more bug surface than
win.

Type of Change

🐛 Bug fix (non-breaking change that fixes an issue)
✨ New feature (non-breaking change that adds functionality)
🔒 Security fix
📝 Documentation update
✅ Tests (adding or improving test coverage)
♻️ Refactor (no behavior change)
🎯 New skill (bundled or hub)

Changes Made

ui-tui/scripts/build.mjs: new esbuild bundler. Aliases @hermes/ink to source (esbuild's __esm helper doesn't await nested async init, which breaks lazy-assigned exports like 'render' when re-exporting through a prebuilt submodule). Stubs
react-devtools-core (dev-only). Injects a createRequire shim for transitive CJS deps. Strips the shebang from src/entry.tsx because Nix patchShebangs mangles '/usr/bin/env -S node --max-old-space-size=8192 --expose-gc' — it drops the 'node' token. The Python
launcher always invokes node explicitly, so the shebang is redundant.
nix/tui.nix: installPhase no longer copies node_modules or the @hermes/ink packages dir.
nix/checks.nix: drop the 'node_modules present' assertion.
hermes_cli/main.py:
- _tui_need_npm_install short-circuits when dist/entry.js exists and no package-lock.json is present. That is the prebuilt-bundle layout (nix / packaged release) and there is nothing to install. Without this, the launcher tried to npm install in a
  non-existent site-packages/ui-tui path.
- Rewrote _make_tui_argv into three explicit paths: (1) HERMES_TUI_DIR set → run prebuilt dist/entry.js; (2) --dev → tsx src/entry.tsx (no build); (3) normal → always npm run build, then run.
- Deleted dead helpers: _find_bundled_tui, _tui_build_needed, _hermes_ink_bundle_stale.
- Added a guard so --dev + HERMES_TUI_DIR errors out instead of silently failing (prebuilt bundle has no source to hot-reload).
tests/hermes_cli/test_tui_npm_install.py: removed the 3 staleness-walk tests that exercised deleted helpers; kept all _tui_need_npm_install tests.

How to Test

run tui under nix
see it still works fine
run tui not under nix
see it still works fine
try hermes --tui --dev with HERMES_TUI_DIR set → should error out cleanly
:3

Checklist

Code

I've read the Contributing Guide
My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
I searched for existing PRs to make sure this isn't a duplicate
My PR contains only changes related to this fix/feature (no unrelated commits)
I've run pytest tests/ -q and all tests pass
I've added tests for my changes (required for bug fixes, strongly encouraged for features)
I've tested on my platform:

Documentation & Housekeeping

I've updated relevant documentation (README, docs/, docstrings) — or N/A
I've updated cli-config.yaml.example if I added/changed config keys — or N/A
I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Copilot

Pull request overview

Refactors the Hermes TUI build/distribution pipeline to produce a single bundled dist/entry.js with esbuild, allowing Nix (and other packaged layouts) to ship the TUI without runtime node_modules.

Changes:

Add an esbuild-based bundler script to generate a self-contained dist/entry.js.
Update Nix packaging/checks to stop copying/asserting runtime node_modules.
Adjust the CLI’s TUI launcher logic to skip npm installs for the prebuilt-bundle layout (no package-lock.json + dist/entry.js present).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ui-tui/scripts/build.mjs	New esbuild bundling script producing a single `dist/entry.js` and stripping the shebang.
ui-tui/package.json	Replace build pipeline with esbuild script; simplify dev script.
nix/tui.nix	Stop installing/copying runtime `node_modules`; ship only `dist/` + `package.json`.
nix/checks.nix	Remove assertion that `node_modules` exists in the packaged TUI.
hermes_cli/main.py	Skip npm install when running from a prebuilt, self-contained TUI bundle layout.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Replace the tsc + babel pipeline with a single esbuild invocation that produces a self-contained dist/entry.js. The nix TUI derivation no longer copies node_modules — only dist/ + package.json ship, shrinking the output from hundreds of MB to ~2.9 MB. - ui-tui/scripts/build.mjs: new esbuild bundler. Aliases @hermes/ink to source (esbuild's __esm helper doesn't await nested async init, which breaks lazy-assigned exports like 'render' when re-exporting through a prebuilt submodule). Stubs react-devtools-core (dev-only). Injects a createRequire shim for transitive CJS deps. Strips the shebang from src/entry.tsx because Nix patchShebangs mangles '/usr/bin/env -S node --max-old-space-size=8192 --expose-gc' — it drops the 'node' token. The Python launcher always invokes node explicitly, so the shebang is redundant. - nix/tui.nix: installPhase no longer copies node_modules or the @hermes/ink packages dir. - nix/checks.nix: drop the 'node_modules present' assertion. - hermes_cli/main.py: _tui_need_npm_install short-circuits when dist/entry.js exists and no package-lock.json is present. That is the prebuilt-bundle layout (nix / packaged release) and there is nothing to install. Without this, the launcher tried to npm install in a non-existent site-packages/ui-tui path.

the esbuild pipeline (scripts/build.mjs) already bundles ink into a single self-contained dist/entry.js. remove the Dockerfile steps that manually copied packages/hermes-ink into node_modules/@hermes/ink and ran a nested npm install there. - Dockerfile: simplify TUI build step to just 'npm run build' - hermes_cli/main.py: _tui_build_needed now checks dist/entry.js staleness against source files before falling back to the old ink-bundle.js logic - tests: update TUI npm install tests and drop the Dockerfile contract test for the removed ink materialization step

github-actions · 2026-05-11T20:16:39Z

🔎 Lint report: `fix/bundle-size` vs `origin/main`

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 8168 on HEAD, 8168 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 4303 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

The old mtime-tracking staleness machinery (_tui_build_needed, _hermes_ink_bundle_stale, _find_bundled_tui) tried to avoid rebuilding by comparing source timestamps to dist/entry.js. This was fragile and added ~100 lines of code. Replace with three clear paths: 1. HERMES_TUI_DIR set (prebuilt/nix): just node dist/entry.js, no build 2. --dev mode: tsx src/entry.tsx, no build, hot reload 3. Normal: always npm run build (esbuild is ~1s, correctness > caching) Also error when HERMES_TUI_DIR is set with --dev (footgun: prebuilt bundle has no source code to hot-reload).

ui-tui: bundle with esbuild, drop runtime node_modules

alt-glitch added type/refactor Code restructuring, no behavior change P3 Low — cosmetic, nice to have comp/tui Terminal UI (ui-tui/ + tui_gateway/) area/nix Nix flake, NixOS module, container packaging labels Apr 30, 2026

OutThisLife requested review from OutThisLife and Copilot and removed request for OutThisLife April 30, 2026 17:47

OutThisLife approved these changes Apr 30, 2026

View reviewed changes

Copilot started reviewing on behalf of OutThisLife April 30, 2026 17:48 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Comment thread ui-tui/package.json Outdated

Comment thread hermes_cli/main.py

Comment thread ui-tui/scripts/build.mjs Outdated

ethernet8023 force-pushed the fix/bundle-size branch from 8f418ff to 040867a Compare April 30, 2026 19:30

ethernet8023 force-pushed the fix/bundle-size branch from 040867a to 42627b4 Compare April 30, 2026 19:38

github-actions Bot and others added 6 commits April 30, 2026 19:49

fix(nix): refresh npm lockfile hashes

279504d

fix(tui): update comments

42df7ec

fix(tui): don't hardcode /home/bb

242659f

fix(tui): update README

9d645d9

Merge remote-tracking branch 'origin/main' into fix/bundle-size

3197b4d

ethernet8023 merged commit 825bd50 into main May 11, 2026
18 of 21 checks passed

ethernet8023 deleted the fix/bundle-size branch May 11, 2026 21:46

This was referenced May 12, 2026

Ecosystem Digest — 2026-05-12 Haderach-Ram/openclaw-radar#4

Open

Ecosystem Digest — 2026-05-12 Haderach-Ram/openclaw-radar#5

Open

02356abc pushed a commit to 02356abc/hermes-agent that referenced this pull request May 14, 2026

Merge pull request NousResearch#18036 from NousResearch/fix/bundle-size

3f0c933

ui-tui: bundle with esbuild, drop runtime node_modules

jsboige pushed a commit to jsboige/hermes-agent that referenced this pull request May 14, 2026

Merge pull request NousResearch#18036 from NousResearch/fix/bundle-size

5ddb533

ui-tui: bundle with esbuild, drop runtime node_modules

teknium1 mentioned this pull request May 24, 2026

perf(tui): fix hardcoded esbuild output filename causing 6s blocking loop #20322

Closed

19 tasks

gweeteve pushed a commit to gweeteve/hermes-agent that referenced this pull request Jun 2, 2026

Merge pull request NousResearch#18036 from NousResearch/fix/bundle-size

a968f1a

ui-tui: bundle with esbuild, drop runtime node_modules

mitlithands mentioned this pull request Jun 8, 2026

fix(cli): fall back to prebuilt TUI bundle when npm fails #40694

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ui-tui: bundle with esbuild, drop runtime node_modules#18036

ui-tui: bundle with esbuild, drop runtime node_modules#18036
ethernet8023 merged 8 commits into
mainfrom
fix/bundle-size

ethernet8023 commented Apr 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ethernet8023 commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Type of Change

Changes Made

How to Test

Checklist

Code

Documentation & Housekeeping

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 Lint report: fix/bundle-size vs origin/main

ruff

ty (type checker)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ethernet8023 commented Apr 30, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

🔎 Lint report: `fix/bundle-size` vs `origin/main`