domdomdom

domdomdom

Lightweight CLI for running JS against an HTML page. Powered by happy-dom — no browser binary, no Playwright, no MCP server. Runs on Bun ≥1.3 or Node ≥23.6.

Invocation

Pipe the JS via stdin. Always use --json (parseable output) and --timeout (bound execution):

echo "<JS expression or block>" | domdomdom --json --timeout 3000 [SOURCE]

Source forms (pick one):

Form	Meaning
https://example.com	fetched URL
./local.html	local file
--html '<title>x</title>'	inline HTML
(omitted)	about:blank

Single-line expressions auto-return. Multi-line code: write return explicitly.

Output shape

Stdout is one line of JSON. Branch on .ok.

// success
{ "ok": true, "result": <any>, "logs": [{"level": "log"|"warn"|"error"|"info"|"debug", "message": "..."}] }

// failure
{ "ok": false, "error": { "kind": "eval"|"timeout"|"setup", "message": "...", "stack": "..." }, "logs": [...] }

Exit codes: 0 ok · 1 eval error · 2 timeout · 3 setup/usage. Use the exit code as a cheap pre-check.

Patterns

Extract data from a fetched page

echo 'return [...document.querySelectorAll("h2")].map(h => h.textContent.trim())' \
  | domdomdom --json --timeout 5000 https://news.ycombinator.com

Verify a bundle attaches its export

echo 'return typeof window.MyLib' | domdomdom --json ./dist/test.html

Preload stubs before user code

echo 'return await fetch("/api/x").then(r => r.json())' \
  | domdomdom --json --inject ./stubs.js ./page.html

Useful flags

--inject <f> (preload, repeatable) · --script <f> (code from file) · --module (ESM) · --user-agent <s> · --no-console (drop logs) · --viewport WxH. Run domdomdom --help for the full list.

Don't reach for this when

Need	Use instead
Layout, getComputedStyle, screenshots	Playwright
Click, scroll, type, navigation flows	Playwright
Hard isolation for untrusted JS	Playwright sandbox
Parse HTML without executing scripts	linkedom (faster)

Limits to remember

• No layout. Computed styles return '' for unstyled elements.
• Async timeout only. --timeout won't kill a synchronous while(true){} (shared event loop). For a hard ceiling, wrap in shell timeout: timeout 5s domdomdom ....
• No bare specifiers in <script type="module">. Relative imports work.
• Stack traces point at evaluated-script offsets, not the user's .ts source.

When things go wrong

• ok: true but result: undefined — user's code didn't return. In multi-statement code, return is required.
• error.kind: "setup" — bad input: missing file, both --html and a positional source, malformed URL.
• Empty logs unexpectedly — check whether --no-console was passed.