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

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 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 (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 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) 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. Both helpers are re-exported through 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:

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:

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 after being defined in 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, 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.

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