# How to Perform Network Requests from the Node.js Server or Browser Context in Ego-Lite

> Easily perform network requests in Node.js or browser contexts with Ego-Lite. Discover the unified fetch facade for server and browser HTTP calls.

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

---

**Ego-Lite provides a unified `fetch` facade that exposes `fetch.server` for Node.js HTTP requests and `fetch.browser` for requests executed within the controlled browser page, both implemented in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) and registered in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).**

Ego-Lite is an open-source browser automation framework that simplifies agent scripting by abstracting away environment-specific networking details. When building automation workflows, you often need to perform network requests from either the Node.js runtime or directly from the browser page context. The framework provides a consistent API through its **`fetch` facade**, allowing agents to execute HTTP requests seamlessly regardless of the execution environment.

## Server-Side Network Requests with `fetch.server`

Agent scripts running in the Node.js environment can issue HTTP requests using **`fetch.server`**, implemented as `serverFetch` in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) (lines 11-27).

This function wraps Node.js's native global `fetch` and enforces a **browser-like User-Agent** header (`"Mozilla/5.0"`) to ensure compatibility with servers that block non-browser clients. It accepts a URL string and an options object containing `headers`, `method`, `body`, and `timeout` (specified in seconds).

If the response status is not `ok`, the function throws a descriptive error containing the status code and status text. On success, it returns the response body as a plain text string.

```typescript
// Request from Node.js server context
const html = await fetch.server('https://example.com', {
  headers: { 'Accept': 'text/html' },
  timeout: 10,
});
console.log('Response length:', html.length);

```

## Browser Context Network Requests with `fetch.browser`

For requests that must originate from the browser page itself—useful for maintaining cookies, session state, or bypassing CORS restrictions—use **`fetch.browser`**, implemented as `browserFetch` in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) (lines 35-52).

This function serializes the request parameters and injects them into the active page using the **`evaluate`** helper from [`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts), which executes code via the Chrome DevTools Protocol (CDP). The request runs inside an async IIFE within the page context, using the browser's native `fetch` implementation.

To ensure consistency with the server-side behavior, `browserFetch` implements a manual **`AbortController`** to enforce the timeout limit. Errors propagate with the same message format as `serverFetch`, maintaining a predictable debugging experience across both contexts.

```typescript
// Request from within the browser page
const json = await fetch.browser('/api/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ foo: 'bar' }),
  timeout: 5,
});
const data = JSON.parse(json);

```

## Facade Registration and Helper Context

The dual `fetch` API is exposed to agent scripts through the helper context created in **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** (lines 18-31). Here, the `fetch` object containing both `server` and `browser` methods is attached to the agent's execution context.

Documentation for these helpers is automatically generated and available via the `help('fetch')` command, defined in the `FACADE_HELP` mapping within [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts).

## Configuration Options and Error Handling

Both `fetch.server` and `fetch.browser` accept a consistent options interface:

- **`headers`**: Object containing HTTP header key-value pairs
- **`method`**: HTTP method string (GET, POST, PUT, DELETE, etc.)
- **`body`**: Request payload as string
- **`timeout`**: Maximum wait time in seconds before aborting the request

Error handling is normalized across both environments. When a request fails or returns a non-2xx status code, the functions throw descriptive errors containing the status code and response details. This unified error format allows agents to handle network failures predictably without environment-specific branching logic.

## Summary

- Ego-Lite provides a **unified `fetch` facade** with `fetch.server` for Node.js and `fetch.browser` for page-context requests
- **`serverFetch`** in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) wraps Node's native fetch with a forced Mozilla User-Agent
- **`browserFetch`** in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) executes requests via CDP's `evaluate` function within the browser page
- Both methods support **custom headers**, **HTTP methods**, **request bodies**, and **configurable timeouts**
- The facade is registered in **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** and documented through the built-in help system
- Error handling is consistent across environments, throwing descriptive messages for non-ok responses

## Frequently Asked Questions

### What is the difference between `fetch.server` and `fetch.browser` in Ego-Lite?

`fetch.server` executes HTTP requests from the Node.js runtime environment using Node's native global fetch, while `fetch.browser` injects and executes the fetch call within the currently controlled browser page via Chrome DevTools Protocol. Use `fetch.server` for direct API calls from the automation script, and `fetch.browser` when you need the request to originate from the browser context to maintain session cookies or bypass CORS restrictions.

### How does Ego-Lite handle request timeouts for browser-context fetches?

The `browserFetch` implementation in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) manually instantiates an `AbortController` and passes its signal to the fetch call executed within the page. If the specified timeout duration elapses before the response returns, the controller aborts the request, throwing a timeout error that matches the format used by `serverFetch` for consistency.

### Can I send POST requests with JSON payloads using the Ego-Lite fetch facade?

Yes, both `fetch.server` and `fetch.browser` support POST requests with custom headers and bodies. Pass `method: 'POST'`, set the appropriate `Content-Type` header (typically `application/json`), and provide the serialized JSON string in the `body` option. The response is always returned as plain text, which you can then parse using `JSON.parse()`.

### Where is the fetch facade registered and exposed to agent scripts?

The `fetch` object containing both `server` and `browser` methods is registered in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 18-31) as part of the helper context creation. This registration makes the methods available globally within agent scripts. Documentation for these methods is maintained in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts) within the `FACADE_HELP` map and accessible via the `help('fetch')` command.