@growthbook/edge-utils

中文文档
0.3.0发布于 2026/11/03MITTypeScriptCommonJS近 30 天下载 1.2万

Edge worker base app

原始使用文档
文档目录7 节
  1. Installation
  2. Implement our Edge App request handler
  3. Set up environment variables
  4. Set up payload caching (optional)
  5. Configuration
  6. Lifecycle hooks
  7. Further reading

GrowthBook Edge App (base)

GrowthBook is a modular Feature Flagging and Experimentation platform.

The GrowthBook Edge App provides turnkey Visual Editor and URL Redirect experimentation on edge without any of the flicker associated with front-end experiments while also supporting manual feature flagging and experimentation. It runs as a smart proxy layer between your application and your end users. It also can inject a fully-hydrated front-end SDK onto the rendered page, meaning no extra network requests needed.

  • Automatically run server-side or hybrid Visual Experiments without redraw flicker.
  • Automatically run server-side or hybrid URL Redirect Experiments without flicker or delay.
  • Perform custom feature flagging and experimentation logic using lifecycle hooks.
  • Inject the JavaScript SDK with hydrated payload, allowing the front-end to pick up where the edge left off without any extra network requests.

[!NOTE]

This is a vendor-agnostic base app for the GrowthBook Edge App. It is used by our vendor-specific Edge Apps (Cloudflare Workers, Lambda@Edge). You can also easily build a custom implementation for your edge provider.

Installation

Implement our Edge App request handler

To run the edge app, add our base app to request handler to your project. You will need to manually build app context and helper functions:

import { edgeApp, getConfig, defaultContext } from "@growthbook/edge-utils";

export async function handler(request, env) {
  const context = await init(env);
  return edgeApp(context, request);
}

function init(env) {
  const context = defaultContext;
  context.config = getConfig(env);
  context.helpers = {
    // define utility functions for request/response manipulation
  };
return context;
}

Set up environment variables

Add these required fields, at minimum, to your environment variables:

PROXY_TARGET="https://internal.mysite.io"  # The non-edge URL to your website
GROWTHBOOK_API_HOST="https://cdn.growthbook.io"
GROWTHBOOK_CLIENT_KEY="abc123"
GROWTHBOOK_DECRYPTION_KEY="qwerty1234"  # Optional

See the complete list of environment variables in the Configuration section.

Set up payload caching (optional)

Set up an edge key-val store and optionally use a GrowthBook SDK Webhook to keep feature and experiment values synced between GrowthBook and your edge worker. This eliminates network requests from your edge to GrowthBook.

Configuration

The GrowthBook Edge App supports a number of configuration options available via environment variables:

Proxy behavior

  • PROXY_TARGET - Origin (non-edge) base URL to your website
  • FORWARD_PROXY_HEADERS - "true" or "1" to preserve response headers from your server (default true)
  • FOLLOW_REDIRECTS - "true" or "1" to follow redirects when processing an origin response (default true)
  • USE_DEFAULT_CONTENT_TYPE - "true" or "1" to assume a content-type of "text-html" if no "Content-Type" header was set (default false).
  • PROCESS_TEXT_HTML_ONLY - "true" or "1" to only process server responses with the Content-Type: text/html header set – others will be proxied through (default true).
  • AUTO_INFLATE - "true" or "1" to automatically unzip gzipped content. Not needed for most vendors (default: false).
  • NOCACHE_ORIGIN - "true" or "1" to send "nocache" headers on origin requests. Not needed for most vendors (default: false).
  • NODE_ENV - default: production
  • ROUTES - JSON encoded array of Routes, rules for intercepting, proxy passing, or erroring based on request URL pattern matching

Experiment behavior

  • RUN_VISUAL_EDITOR_EXPERIMENTS - One of everywhere, edge, browser, or skip (default everywhere)
  • DISABLE_JS_INJECTION - "true" or "1" to skip injecting JavaScript coming from a Visual Experiment (default false)
  • RUN_URL_REDIRECT_EXPERIMENTS - One of everywhere, edge, browser, or skip (default browser)
  • RUN_CROSS_ORIGIN_URL_REDIRECT_EXPERIMENTS - One of everywhere, edge, browser, or skip (default browser)
  • INJECT_REDIRECT_URL_SCRIPT - "true" or "1" to mutate browser URL via window.history.replaceState() to reflect the redirected URL (default true)
  • MAX_REDIRECTS - Number of on-edge redirects calculated before bailing out. Only the final redirect is fetched from your origin. (default 5)
  • EXPERIMENT_URL_TARGETING - URL targeting for visual editor and redirect experiments: request targets using the edge worker URL; origin uses the origin server URL. (default request)

Front-end SDK hydration

  • SCRIPT_INJECTION_PATTERN - Inject the GrowthBook SDK before this token (default </head>)
  • DISABLE_INJECTIONS - "true" or "1" to disable SDK injection entirely, including tracking callbacks (default false)

GrowthBook SDK behavior

  • GROWTHBOOK_API_HOST - Required
  • GROWTHBOOK_CLIENT_KEY - Required
  • GROWTHBOOK_DECRYPTION_KEY - Required when using an encrypted SDK Connection

  • STALE_TTL - In-memory SDK cache TTL (default 1 min = 60000).
  • GROWTHBOOK_TRACKING_CALLBACK - String representation of custom JavaScript client-side tracking callback.
  • ENABLE_STREAMING - "true" or "1" to enable front-end SSE streaming (default false)
  • ENABLE_STICKY_BUCKETING - "true" or "1" to enable Sticky Bucketing, cookie-based by default (default false)
  • STICKY_BUCKET_PREFIX - The name prefix for Sticky Bucketing cookies (default gbStickyBuckets__)

User Attribute behavior

  • PERSIST_UUID - "true" or "1" to write the user's ID to cookie from the edge server instead of from the browser (default false)
  • NO_AUTO_COOKIES - "true" or "1" to avoid writing any cookies (excluding Sticky Buckets) until user permission is granted on front-end via document.dispatchEvent(new CustomEvent("growthbookpersist")); (default false)
  • UUID_COOKIE_NAME - Customize the cookie name for persisting the user's ID (default gbuuid)
  • UUID_KEY - Customize the user identifier name (default id)
  • SKIP_AUTO_ATTRIBUTES "true" or "1" to skip auto-generating targeting attributes (default false)

Lifecycle hooks

  • ALWAYS_PARSE_DOM - Normally the worker will only build a virtual DOM if there are visual changes. Set to "true" or "1" to always build a virtual DOM so that you can access it in lifecycle hooks (ex: onBodyReady)

Misc

  • CONTENT_SECURITY_POLICY - CSP header value
  • EMIT_TRACE_HEADERS - "true" or "1" to set extra headers to detect edge redirect loops and stabilize gbuuid generation (default true).

Lifecycle hooks

You can perform custom logic and optionally return a response at various stages in the Edge App's lifecycle. This allows for expressiveness of custom routing, user attribute mutation, header and body (DOM) mutation, and custom feature flag and experiment implementations – while preserving the ability to automatically run Visual and URL Redirect experiments and SDK hydration.

With each hook, you may mutate any of the provided attributes or return an early response to halt the Edge App processing. The following hooks are available

  • onRequest - Fired on initial user request. Can exit early based on requested URL.
  • onRoute - Fired after standard routing has been processed. Can exit early (proxy) based on manual routing logic.
  • onUserAttributes - Fired after auto-attributes have been assigned to the user. Either enhance the provided attributes object or exit early if desired.
  • onGrowthBookInit - Fired after the Edge App's internal GrowthBook SDK has been initialized. Call SDK functions or exit early if desired.
  • onBeforeOriginFetch - Similar hook to the above; triggers after any URL Redirect experiments have run but before any origin requests have been made.
  • onOriginFetch - Fired immediately after the origin fetch has been made, but before the full response body has been captured. Useful for exiting early based on response status or headers.
  • onBodyReadyParams - Fired once the entire response body has been parsed. In addition to early exiting, you may begin to mutate the final response body via resHeaders and the setBody() method. The text body as well as the optional parsed virtual DOM root (disabled by default, use ALWAYS_PARSE_DOM to enable) are exposed. NOTE: If mutating the root DOM, it is your responsibility to setBody() with the latest changes before the response is returned.
  • onBeforeResponse - The final hook fired before the response is returned to the user, triggering after both visual editor changes and client SDK hydration have been injected. While the virtual DOM is no longer available, this hook can be used to apply any final changes the body via setBody().

Further reading

See the Edge App documentation for more details and examples.

版本与发布记录

@growthbook/edge-utils 共发布 25 个版本,首次发布于 2024/05/07;过去 12 个月发布了 4 个版本。

版本发布日期距今
0.3.0latest2026/11/0314 天前
0.2.92026/05/136 个月前
0.2.82026/02/178 个月前
0.2.72026/02/119 个月前
0.2.62025/08/191.2 年前
0.2.52025/03/201.7 年前

关于 @growthbook/edge-utils 的常见问题

@growthbook/edge-utils 是什么?

Edge worker base app

如何安装 @growthbook/edge-utils?

在项目目录运行 npm install @growthbook/edge-utils,或使用 pnpm add / yarn add / bun add。

@growthbook/edge-utils 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@growthbook/edge-utils 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@growthbook/edge-utils 可以商用吗?

@growthbook/edge-utils 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@growthbook/edge-utils 的下载量有多少?

根据 npm 官方下载统计,@growthbook/edge-utils 在 2026/10/17 – 2026/11/15 这 30 天内被下载 11,783 次,日均约 393 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@growthbook/edge-utils 还在维护吗?

最新版本 0.3.0 发布于 2026/11/03(14 天前);至今共发布 25 个版本,其中过去 12 个月发布了 4 个;首次发布于 2024/05/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。