# How to Inject Ego-Browser SDK Helpers into globalThis: Complete Guide

> Easily inject ego-browser SDK helpers into globalThis using installEgoSdk. This guide shows how to create helper contexts and define facades like page and browser for your application.

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

---

**To inject Ego-Browser SDK helpers into `globalThis`, use the `installEgoSdk` function exported from [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) in the citrolabs/ego-lite repository, which creates a helper context, removes legacy globals, and defines non-enumerable properties for `page`, `browser`, and other facades on your target object.**

The citrolabs/ego-lite repository provides the Ego-Browser SDK as a set of helper functions designed for browser automation and agent scripting. When you inject ego-browser SDK helpers into `globalThis`, you make utilities like `page`, `browser`, `taskSpaces`, `site`, and `fetch` available globally within your execution environment, enabling seamless scripting without explicit imports in every module.

## Understanding the SDK Installation Architecture

### The installEgoSdk Function

The core mechanism for injecting helpers resides in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts). This file exports **`installEgoSdk`**, the primary installer function responsible for attaching the SDK to any target object. According to the source code, this function orchestrates the entire injection process by coordinating context creation, legacy cleanup, and property definition.

### Helper Context Creation

Before injection occurs, the installer calls **`helperContext()`** defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 22-36). This function builds the facades for:

- **`page`** – Page manipulation utilities
- **`browser`** – Browser-level controls  
- **`taskSpaces`** – Task space management
- **`site`** – Site-specific skill handlers
- **`fetch`** – Network request helpers

The context function returns an object containing these exposed helpers, which the installer then attaches to the target.

## Step-by-Step Injection Process

When you call `installEgoSdk(target)`, the function executes five distinct operations:

1. **Creates the helper context** – Invokes `helperContext()` to instantiate all facade objects.
2. **Deletes legacy global helpers** – Iterates over `LEGACY_GLOBAL_HELPERS` (e.g., `click`, `goto`) and removes any existing definitions from the target to prevent conflicts (lines 51-57).
3. **Defines non-enumerable properties** – Uses `Object.defineProperty(target, name, { value: exposed, ... })` (lines 66-73 in index.ts) to attach each helper as a non-enumerable property, ensuring they don't appear in `for...in` loops or `Object.keys()`.
4. **Attaches the helper bundle** – Assigns `target.ego.helpers = installed` (lines 94-98), creating a reference to the full helper bundle on the Ego runtime object.
5. **Wraps mutating methods** – Applies `wrapCreateTab` and `wrapInvalidating` (lines 81-84) to Ego-specific methods like `createTab` and `useTaskSpace`, ensuring internal session state remains consistent when these methods are called.

## Automatic vs. Manual Installation

The Ego-Browser SDK supports two installation modes depending on your usage context.

### Automatic Installation (Script Mode)

When importing the module as a script via `node ego-browser ...` or using the default import, the SDK automatically invokes `installEgoSdk()` at the bottom of [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts). This side-effect import immediately populates `globalThis` with all helpers.

```typescript
// Automatic injection on import
import 'ego-browser'

// Helpers are now available on globalThis
await page.goto('https://example.com')
await click('#submit')

```

### Manual Installation (Library Mode)

When using the SDK as a library within your own application, import `installEgoSdk` explicitly and provide a custom target object. This approach allows you to inject helpers into sandboxes, virtual machines, or iframe contexts.

```typescript
import { installEgoSdk } from 'ego-browser'

const sandbox = {}
installEgoSdk(sandbox)

// Use helpers from the custom object
await sandbox.page.goto('https://example.com')
await sandbox.click('#login')

```

## Practical Implementation Examples

### Injecting into a Custom Sandbox

For isolated execution environments, inject helpers into a plain object to avoid polluting the global scope:

```typescript
import { installEgoSdk } from 'ego-browser'

const isolatedContext = {}
installEgoSdk(isolatedContext)

// All helpers available on the isolated context
await isolatedContext.browser.newContext()
await isolatedContext.page.screenshot({ path: 'capture.png' })

```

### Injecting into a VM Context

When running untrusted code in a virtual machine (VM2 or Node.js VM module), inject the SDK into the VM's global object:

```typescript
import { installEgoSdk } from 'ego-browser'
import { VM } from 'vm2'

const vm = new VM()
installEgoSdk(vm.globalThis)

// Helpers available within VM execution
vm.run(`
  await page.goto('https://example.com')
  return browser.version()
`)

```

### Accessing the Helper Bundle

After installation, access the complete helper bundle through the Ego runtime property:

```typescript
installEgoSdk(globalThis)

// Access the raw helper objects
console.log(globalThis.ego.helpers.page)
console.log(globalThis.ego.helpers.browser)

```

## Key Source Files Reference

| File | Role |
|------|------|
| [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | Exports `installEgoSdk`, handles legacy global cleanup, defines helpers on target, and wraps Ego runtime methods. |
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Implements `helperContext()` to build facades for page, browser, taskSpaces, site, and fetch operations. |
| [`package/ego-browser/src/run.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/run.ts) | CLI entry point that triggers automatic SDK installation when the module executes directly. |
| [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/browser-runtime.ts) | Provides session-management utilities (`invalidateSession`, `clearPreferredTarget`) that the installer wraps for consistency. |

## Summary

- **`installEgoSdk`** is the primary function for injecting Ego-Browser SDK helpers, located in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts).
- The installer creates a helper context via `helperContext()` in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts), then attaches facades for `page`, `browser`, `taskSpaces`, `site`, and `fetch`.
- Legacy globals (defined in `LEGACY_GLOBAL_HELPERS`) are automatically purged before injection to prevent naming collisions.
- Helpers are attached as **non-enumerable properties** using `Object.defineProperty`, ensuring they don't interfere with enumeration loops.
- The installation process wraps mutating methods like `createTab` to maintain internal session state consistency.
- You can inject into `globalThis` automatically via side-effect import or manually into custom objects like VM contexts.

## Frequently Asked Questions

### How do I prevent Ego-Browser from polluting the global scope?

Import `installEgoSdk` explicitly and pass a custom object instead of using the automatic installation. This injects ego-browser SDK helpers into your specified target (e.g., a sandbox object) rather than `globalThis`, keeping the global namespace clean while still providing full SDK functionality within your controlled context.

### What happens if legacy global helpers like `click` or `goto` already exist?

The `installEgoSdk` function includes a cleanup phase that iterates over `LEGACY_GLOBAL_HELPERS` and deletes any existing properties with those names from the target object before defining the new helpers. This prevents conflicts between old and new API versions, ensuring consistent behavior according to the implementation in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) (lines 51-57).

### Can I install the SDK helpers into multiple different contexts?

Yes, `installEgoSdk` is designed to be called multiple times with different target objects. Each call creates a fresh helper context and attaches it to the supplied target. This allows you to maintain separate SDK instances in different VM contexts, iframes, or sandboxed environments, each with isolated state and helper references.

### Why are the helpers defined as non-enumerable properties?

The SDK uses `Object.defineProperty` with the non-enumerable flag (lines 66-73 in index.ts) to ensure that helpers like `page` and `browser` don't appear when enumerating object properties with `for...in` loops or `Object.keys()`. This design choice prevents the SDK methods from interfering with user scripts that iterate over global properties, while still making them accessible as direct property references.