# How browserFetch Differs from serverFetch in ego-browser: Network Origin Explained

> Discover how ego-browser's browserFetch and serverFetch differ in network origin. Understand their unique execution environments and implications for HTTP requests.

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

---

**In `ego-browser`, `serverFetch` executes HTTP requests from the Node.js host environment using server-side network origins, while `browserFetch` runs inside the browser page via Chrome DevTools Protocol (CDP) `evaluate`, inheriting the page's cookies, CORS restrictions, and origin context.**

The `ego-browser` package from the `citrolabs/ego-lite` repository provides two distinct fetch utilities that differ fundamentally in network origin. Understanding how `browserFetch` differs from `serverFetch` is essential when you need to either bypass or respect browser-specific security constraints like same-origin policy and cookie-based authentication.

## serverFetch: Node.js Host Environment

The `serverFetch` function executes requests from the server-side Node.js process running the `ego-lite` binary rather than from within the browser page.

### Server Origin Characteristics

According to the implementation in [`package/ego-browser/src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts) (lines 11-27), `serverFetch` exhibits these key behaviors:

- **Network Origin**: Requests originate from the host machine executing the script, not the browser page
- **User-Agent**: Automatically appends a generic `Mozilla/5.0` User-Agent header
- **Credentials**: Does not include browser cookies, session data, or page-specific authentication headers
- **Environment**: Uses Node.js's global `fetch` implementation

```typescript
export async function serverFetch(url, options = {}) {
  // Implementation at src/http.ts lines 11-27
  // Executes from Node host environment
}

```

Use `serverFetch` when you need to bypass CORS restrictions or access resources without the page's cookie context and origin limitations.

## browserFetch: In-Page Browser Execution

The `browserFetch` function executes JavaScript inside the current page context via CDP `evaluate`, making the request behave exactly as if the page's own JavaScript initiated it.

### Browser Origin Characteristics

As implemented in [`package/ego-browser/src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts) (lines 35-52), `browserFetch` operates with these constraints:

- **Network Origin**: Request originates from the browser page's URL context
- **Relative URLs**: Resolves relative paths against the current page's URL (e.g., `/api/data` becomes `https://current-site.com/api/data`)
- **Credentials**: Automatically includes the page's cookies, authentication headers, and session data
- **Security**: Subject to same-origin policy and CORS rules of the loaded site
- **Execution**: Runs via CDP `evaluate` method inside the page context

```typescript
export async function browserFetch(url, options = {}) {
  // Implementation at src/http.ts lines 35-52
  // Executes inside page via CDP evaluate
}

```

Use `browserFetch` when you need to maintain session state or when the target API requires cookies and authentication headers present in the browser storage.

## Practical Usage Examples

Both functions are re-exported from [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (lines 18-101) and exposed in the public API via [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) (line 124).

```typescript
import { serverFetch, browserFetch } from "ego-browser";

// ----- Server-side fetch (runs from Node) -----
const html = await serverFetch("https://example.com/api/data", {
  headers: { "Accept": "application/json" },
});
console.log("Server response:", html);

// ----- Browser-side fetch (runs inside the page) -----
const pageHtml = await browserFetch("/api/data", {
  // No need to specify full URL – it resolves against the current page
  headers: { "Accept": "application/json" },
});
console.log("Browser response:", pageHtml);

```

When the active page is `https://my-site.com`, the `browserFetch("/api/data")` call automatically resolves to `https://my-site.com/api/data` and includes any cookies belonging to that domain. The equivalent `serverFetch` call would require the absolute URL and execute without those credentials from the host machine.

## Summary

- **`serverFetch`** originates from the **Node.js host environment**, uses a generic User-Agent, bypasses browser CORS and cookie restrictions, and requires absolute URLs
- **`browserFetch`** originates from the **browser page context** via CDP `evaluate`, inherits the page's origin and credentials, resolves relative URLs against the current page, and is subject to same-origin policy
- Both functions are implemented in [`package/ego-browser/src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/http.ts) and re-exported through [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)
- Choose `serverFetch` for unrestricted server-side data retrieval; choose `browserFetch` when you need the page's authenticated session or to respect site-specific CORS policies

## Frequently Asked Questions

### Does browserFetch respect the page's CORS policy?

Yes. Because `browserFetch` executes inside the page context via CDP `evaluate` as implemented in [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) lines 35-52, the request is subject to the same Cross-Origin Resource Sharing (CORS) restrictions and same-origin policy as any JavaScript running in that page. If the request violates CORS, the browser will block it exactly as it would for native `fetch` calls.

### Can serverFetch access browser cookies?

No. `serverFetch` runs in the Node.js host environment according to [`src/http.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/http.ts) lines 11-27, completely outside the browser sandbox. It does not have access to the page's `document.cookie`, `localStorage`, or any browser-stored credentials unless you manually extract and pass them in the `headers` option.

### How do relative URLs resolve differently between the two functions?

`browserFetch` resolves relative URLs against the current page's URL (e.g., `/api` becomes `https://current-site.com/api`), while `serverFetch` requires absolute URLs since it has no page context to resolve against. Attempting to pass a relative URL to `serverFetch` results in an error because the Node.js `fetch` implementation lacks a base URL reference.

### Which fetch method should I use for scraping authenticated data?

Use `browserFetch` when scraping data that requires session cookies or authentication tokens stored in the browser. Since it executes in the page context, it automatically includes these credentials. Use `serverFetch` only when you need to bypass CORS restrictions or when handling unauthenticated public APIs where the server origin provides an advantage.