How to Use the ego-browser Harness as a Module in Node.js

Install the ego-browser-v2 package, import installEgoSdk from the entry point, and invoke it to expose Playwright-style helpers on globalThis or a custom target object.

The citrolabs/ego-lite repository provides a pure JavaScript/TypeScript module that integrates browser automation directly into Node.js applications without requiring the CLI. By using the ego-browser harness as a module, you gain programmatic access to high-level CDP wrappers, automatic session handling, and Playwright-compatible facades. This approach requires Node.js version 22 or higher and installs via the package name ego-browser-v2.

Installation and Basic Setup

Install the Package

The module is published to npm as ego-browser-v2. Add it to your project using your preferred package manager.

npm install ego-browser-v2

Import the SDK Entry Point

According to the source code in src/index.ts, the package entry point exports installEgoSdk and re-exports all public helpers from src/helpers.ts. Import these into your ES module or TypeScript file.

import { installEgoSdk, helperContext } from "ego-browser-v2";

Installing the ego-browser Harness

The installEgoSdk function (implemented in src/index.ts around lines 44-65) wires the helper context onto a target object, optionally wrapping each helper to await the SDK-ready signal before executing.

Global Installation on globalThis

Calling installEgoSdk() without arguments injects the entire helper surface onto globalThis, matching the behavior of the original CLI harness.

// Installs page, browser, taskSpaces, site, and fetch onto globalThis
installEgoSdk();

After installation, helpers like page, browser, and taskSpaces become available as global variables.

Custom Namespace Installation

To avoid global side effects, pass a custom target object as the first argument. You can optionally provide a specific helper context via the second argument.

const myApi = {};
installEgoSdk(myApi, {
  context: helperContext()
});

// Access helpers via myApi.page, myApi.taskSpaces, etc.

Using the Exposed Helpers

Once installed, the harness exposes several high-level facades defined in src/helpers.ts. These wrappers handle automatic session management, transient failure retries, and CDP protocol communication.

Page Automation with the page Facade

The page object mirrors the Playwright API, providing methods like goto(), title(), and locator().

await page.goto("https://example.com");
const title = await page.title();
await page.locator("button").click();

Multi-Tab Management with taskSpaces

The taskSpaces facade enables named workspace management across multiple browser tabs.

const space = await taskSpaces.useOrCreate("my-workspace");
await page.goto("https://github.com/citrolabs/ego-lite");
await taskSpaces.complete(space.id, { keep: true });

Site-Specific Skills with site

The site facade executes learned automation tools against specific domains.

const result = await site.runTool("example.com", "extractData", {
  selector: "#main"
});

Complete Implementation Examples

Minimal Setup with Global Injection

Create an index.mjs file that installs the SDK globally and performs basic navigation.

import { installEgoSdk } from "ego-browser-v2";

installEgoSdk();

async function demo() {
  await page.goto("https://example.com");
  console.log("Title:", await page.title());
  await page.locator("a[href*=login]").click();
  await page.screenshot({ path: "login.png" });
}

demo().catch(console.error);

Isolated API Object Pattern

Encapsulate the SDK in a separate module to prevent global namespace pollution.

// myEgo.js
import { installEgoSdk, helperContext } from "ego-browser-v2";

const egoApi = {};
installEgoSdk(egoApi, { context: helperContext() });

export default egoApi;

// usage.mjs
import ego from "./myEgo.js";

async function run() {
  await ego.page.goto("https://news.example");
  const headlines = await ego.page.locator("h1").allInnerTexts();
  console.log(headlines);
}
run().catch(console.error);

Working with Task Spaces

Manage complex multi-page workflows using named task spaces.

import { installEgoSdk } from "ego-browser-v2";

installEgoSdk();

async function workInTaskSpace() {
  const space = await taskSpaces.useOrCreate("my-workspace");
  await page.goto("https://github.com/citrolabs/ego-lite");
  await page.locator("a[href*='README']").click();
  await taskSpaces.complete(space.id, { keep: true });
}
workInTaskSpace().catch(console.error);

SDK Architecture and Source Locations

Understanding the internal structure helps when debugging or extending the harness.

• src/index.ts: Contains the installEgoSdk implementation (lines 44-65), CLI runner logic, and the main entry point exports.
• src/helpers.ts: Defines the helperContext() builder and exports the page, browser, taskSpaces, and site facades.
• src/cdp-eval.ts: Provides low-level CDP evaluation utilities consumed by the high-level helpers.
• src/driver/: Houses concrete action implementations for pointer events, keyboard input, and navigation.

The helperContext() function creates a cohesive context that wraps raw CDP calls, adds automatic session handling, and provides retry logic for transient failures.

Summary

• Install the ego-browser harness as a module via npm install ego-browser-v2 for Node.js ≥ 22.
• Import installEgoSdk from the entry point (src/index.ts) to initialize the SDK.
• Call installEgoSdk() without arguments to expose helpers on globalThis, or pass a custom object to avoid global side effects.
• Access Playwright-style automation through the page facade, multi-tab management via taskSpaces, and domain-specific tools via site.
• The helperContext() wrapper in src/helpers.ts manages CDP sessions and automatic retries behind the scenes.

Frequently Asked Questions

What is the difference between ego-browser-v2 and the CLI harness?

The CLI harness runs automation scripts in a standalone process, while the ego-browser-v2 module allows you to embed the same functionality directly into your Node.js application as a library import, giving you finer control over the runtime environment.

Can I use ego-browser without polluting the global scope?

Yes. Instead of calling installEgoSdk() with no arguments, pass an empty object as the first parameter: installEgoSdk(myApi). This installs all helpers onto myApi rather than globalThis, keeping your global namespace clean.

Which Node.js version is required for ego-browser-v2?

The module requires Node.js version 22 or higher, as specified in the package metadata and source code requirements. Older versions may not support the specific JavaScript features or APIs used in the harness.

How does the page facade relate to Playwright?

The page object exported from src/helpers.ts provides a Playwright-compatible API surface, implementing methods like goto(), title(), and locator() that wrap underlying CDP calls with automatic session management and retry logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}