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

> Easily integrate ego-browser harness into your Node.js project. Install ego-browser-v2 and import installEgoSdk to leverage Playwright-style helpers for efficient testing.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-07-31

---

**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.

```bash
npm install ego-browser-v2

```

### Import the SDK Entry Point

According to the source code in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts), the package entry point exports `installEgoSdk` and re-exports all public helpers from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts). Import these into your ES module or TypeScript file.

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

```

## Installing the ego-browser Harness

The `installEgoSdk` function (implemented in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/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.

```javascript
// 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.

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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()`.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

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

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

export default egoApi;

```

```javascript
// 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.

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)**: Contains the `installEgoSdk` implementation (lines 44-65), CLI runner logic, and the main entry point exports.
- **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)**: Defines the `helperContext()` builder and exports the `page`, `browser`, `taskSpaces`, and `site` facades.
- **[`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.