# browserFetch vs serverFetch in ego-lite: HTTP Helper Functions Explained

> Understand the difference between browserFetch and serverFetch in ego-lite. Learn how serverFetch uses Node.js fetch while browserFetch leverages CDP for in-browser requests. Optimize your HTTP calls.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: deep-dive
- Published: 2026-08-04

---

**`serverFetch` executes HTTP requests from the Node.js runtime using the global `fetch` API, while `browserFetch` injects and runs fetch calls directly within the browser page context via Chrome DevTools Protocol evaluation, enabling access to page-specific resources and relative URLs.**

The `ego-lite` library provides these specialized HTTP utilities within the `ego-browser` package to support different automation scenarios. Understanding the difference between `browserFetch` and `serverFetch` is critical for choosing the appropriate method based on whether you need server-side data retrieval or in-page network requests that respect the browser's security context and session state.

## serverFetch: Server-Side HTTP Requests

The [`serverFetch`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts#L11-L27) function operates within the Node.js process, utilizing the native `fetch` implementation available on `globalThis`. According to the source code in `citrolabs/ego-lite`, this helper is designed for making HTTP requests from the server environment outside of any specific browser page context.

In the implementation at [`package/ego-browser/src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts) (lines 11-27), the function constructs a `Request` object with a custom **User-Agent** header to mimic browser behavior. It enforces request timeouts using `AbortSignal.timeout` and automatically throws an error if the response status is not OK. The function returns the response body as a plain text string, making it suitable for fetching absolute URLs when you do not need to leverage the browser's session cookies or CORS policies.

## browserFetch: In-Page Context Execution

The [`browserFetch`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts#L35-L52) function takes a different architectural approach by executing the fetch operation within the page's JavaScript context. This helper uses the `evaluate` function (provided by [`package/ego-browser/src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/cdp-eval.ts)) to inject a fetch call directly into the browser page.

This method allows the request to execute with the page's full security context, including access to **cookies**, **session storage**, and the ability to resolve **relative URLs** against the page's base URL. The implementation creates a manual `AbortController` to handle timeouts and returns the response text after validating the HTTP status. Because the fetch runs inside the page via `evaluate`, it respects the same-origin policies and CORS configurations active for that specific page context.

## Key Architectural Differences

The primary distinction between these helpers lies in their execution environment and capabilities:

- **Execution Context**: `serverFetch` runs in the Node.js runtime, while `browserFetch` executes within the Chromium page context via CDP evaluation.
- **URL Resolution**: `serverFetch` requires absolute URLs, whereas `browserFetch` supports relative URLs that resolve against the current page's address.
- **Authentication**: `browserFetch` automatically includes cookies and authentication headers associated with the page's current session; `serverFetch` requires manual header configuration.
- **Timeout Implementation**: `serverFetch` uses `AbortSignal.timeout`, while `browserFetch` implements timeouts using `AbortController` within the evaluated page script.
- **Return Type**: Both functions return a `Promise<string>` containing the response text and throw errors on non-OK HTTP statuses.

## Source Code Implementation

Both functions accept an options object with the shape `{ headers?, timeout?, method?, body? }`, though they handle the request lifecycle differently based on their environment.

The `serverFetch` implementation (lines 11-27) leverages Node's global fetch with custom header injection. The `browserFetch` implementation (lines 35-52) wraps the page's native `fetch` via the `evaluate` utility defined in [`package/ego-browser/src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/cdp-eval.ts). Both helpers are re-exported through [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) for use in the helper injection context.

## Practical Usage Examples

Use `serverFetch` when making requests to external APIs from the server context:

```javascript
import { serverFetch } from "ego-browser";

const html = await serverFetch("https://api.example.com/data", {
  headers: { Accept: "application/json" },
  timeout: 10
});
console.log("Server response:", html);

```

Use `browserFetch` when you need to interact with endpoints relative to the current page or require session cookies:

```javascript
import { browserFetch } from "ego-browser";

const profileData = await browserFetch("/api/user/profile", {
  method: "GET",
  timeout: 5
});
console.log("Page response:", profileData);

```

## Summary

- **`serverFetch`** operates in the Node.js environment using the global `fetch` API, ideal for absolute URLs and server-side data retrieval.
- **`browserFetch`** executes within the browser page context via CDP evaluation, supporting relative URLs and automatic cookie handling.
- Both functions return response text as `Promise<string>` and throw errors on non-OK HTTP statuses.
- **Timeout handling** differs: `serverFetch` uses `AbortSignal.timeout` while `browserFetch` uses `AbortController` within the page context.
- Both helpers are exported from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) after being defined in [`package/ego-browser/src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts).

## Frequently Asked Questions

### Can I use relative URLs with serverFetch?

No. The `serverFetch` function operates outside the browser page context and requires absolute URLs. If you attempt to use a relative path like `/api/data`, the Node.js fetch implementation will throw an error because it cannot resolve the base URL. Use `browserFetch` for relative URLs.

### Does browserFetch share cookies with the current page?

Yes. Because `browserFetch` executes the fetch operation within the page's JavaScript context using the `evaluate` function, it automatically includes all cookies, session storage, and authentication headers associated with the current page state. This makes it ideal for authenticated API requests.

### What happens if a request times out in browserFetch?

The `browserFetch` implementation creates an `AbortController` within the page context and sets a timeout that aborts the fetch operation if it exceeds the specified duration. When aborted, the promise rejects with an error, allowing your code to catch the timeout and handle it appropriately.

### Are these functions available in the global helper context?

Yes. Both `browserFetch` and `serverFetch` are exported from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), making them available in the injected helper context when using ego-lite's browser automation features. You can import them directly from the `ego-browser` package or access them within evaluated scripts depending on your setup.