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

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 (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

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 (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

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 (lines 18-101) and exposed in the public API via src/index.ts (line 124).

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 and re-exported through 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}