@rxflex/rom

Node.js bindings for the ROM browser-like runtime.

This package exposes a small JavaScript API on top of ROM:

• eval()
• evalAsync()
• evalJson()
• goto()
• setContent()
• content()
• evaluate()
• waitForSelector()
• waitForFunction()
• click()
• fill()
• textContent()
• innerHTML()
• locator()
• surfaceSnapshot()
• fingerprintProbe()
• runFingerprintJsHarness()
• fingerprintJsVersion()

It prefers a native napi-rs bridge when available and falls back to the ROM CLI bridge otherwise.

Install

npm install @rxflex/rom

Usage

import { RomRuntime, hasNativeBinding } from "@rxflex/rom";

const runtime = new RomRuntime({
  href: "https://example.test/",
  referrer: "https://referrer.example/",
  cors_enabled: false,
  proxy_url: process.env.ROM_PROXY_URL ?? null,
});

const href = await runtime.evalAsync("(async () => location.href)()");
const snapshot = await runtime.surfaceSnapshot();

console.log("native:", hasNativeBinding());
console.log(href);
console.log(snapshot.fetch);

await runtime.evalAsync("(async () => { globalThis.__romValue = 42; return 'ok'; })()");
console.log(await runtime.evalAsync("(async () => String(globalThis.__romValue))()"));

await runtime.setContent(
  '<div id="app"><input id="name" /><button id="go">Go</button><span id="out"></span></div>' +
    '<script>document.querySelector("#go").addEventListener("click",()=>{document.querySelector("#out").textContent=document.querySelector("#name").value;});</script>',
);
await runtime.fill("#name", "ROM");
await runtime.click("#go");
console.log(await runtime.textContent("#out"));

Config keys use the Rust runtime field names, so use snake_case such as cors_enabled and proxy_url. cors_enabled is false by default. When the native addon is loaded, one RomRuntime instance keeps JS globals alive across multiple eval() and evalAsync() calls. The page-like helpers such as goto(), setContent(), click(), and waitForSelector() require the native binding because CLI bridge mode is stateless across calls. For cookie seeding, the wrapper accepts either serialized cookie_store, a raw cookie header string such as "api_uid=seeded; _nano_fp=abc", or a cookies alias with string/object/array inputs. For storage seeding, the wrapper accepts local_storage and session_storage as serialized JSON objects, plain JS objects, or entry arrays such as [['VerifyAuthToken', 'seeded']]. The default navigator surface is Chrome-like, including navigator.userAgent, navigator.vendor, and navigator.userAgentData.

Optional native build

npm run build:native

Local npm pack and npm publish still build the native addon for the current platform via prepack. Tagged GitHub releases assemble multi-platform prebuilds and publish a single npm package that includes:

• linux-x64-gnu
• win32-x64-msvc
• darwin-x64
• darwin-arm64

At runtime the loader picks the matching binary from prebuilds/<platform>/rom_node_native.node.

Common methods

• eval(script)
• evalAsync(script)
• evalJson(script, { async })
• goto(url, options)
• setContent(html, options)
• content()
• evaluate(pageFunctionOrExpression, arg)
• waitForSelector(selector, options)
• waitForFunction(pageFunctionOrExpression, arg, options)
• click(selector, options)
• fill(selector, value, options)
• textContent(selector, options)
• innerHTML(selector, options)
• locator(selector)
• surfaceSnapshot()
• fingerprintProbe()
• runFingerprintJsHarness()
• fingerprintJsVersion()

Environment

• ROM_NATIVE_NODE_BINDING: explicit path to a compiled .node addon
• ROM_FORCE_CLI_BRIDGE=1: disable the native path and force CLI fallback
• ROM_BRIDGE_BIN: explicit path to the rom_bridge executable
• ROM_BRIDGE_CWD: working directory used by the CLI fallback
• ROM_PROXY_URL: convenience env var you can forward into proxy_url

More docs

• Root guide: ../../README.md
• LLM guide: ../../LLMS.md