Choose an evaluation approach

Compare local Node.js, direct server HTTP, and publishable browser HTTP evaluation.

Choose an evaluation approach by trust boundary first, then latency, resilience, and freshness. Credentials bind to one project environment, so callers never select an environment per request.

Approach	Credential	Decision location	Freshness	Best fit
Node.js SDK	`runtime:snapshot`	Application process	ETag polling, 30 seconds by default	Trusted Node.js services
Server HTTP	`runtime:evaluate`	FeatureGate API	Current hosted configuration	Non-Node servers and central decisions
Browser HTTP	`client:evaluate`	FeatureGate API	Current exposed configuration	Presentation flags in web clients

Local Node.js evaluation

Use the released @featuregate/node package for trusted Node.js applications. It loads the full environment snapshot, evaluates without a request-time network round trip, and refreshes in the background.

Advantages:

Low and predictable evaluation latency.
Continued evaluation from the last successful snapshot during refresh failure.
Local targeting context that never leaves the process.
Typed value and details getters.

Tradeoffs:

Configuration is bounded by polling freshness.
Startup needs an explicit initialization policy.
Every process owns its refresh lifecycle and error monitoring.
Snapshot keys expose all active server configuration in the environment.

Create one client per runtime key and reuse it. Do not create a client for each request.

Direct server HTTP evaluation

Use POST /v1/evaluate when the runtime cannot use the Node.js SDK or current hosted configuration is more important than in-process latency.

Batch decisions needed by one operation. Set a timeout shorter than the operation budget and use the request's typed defaults when the API cannot complete.

HTTP evaluation introduces a network dependency into the request path. It also gives FeatureGate privacy-safe hosted request and per-flag totals that local SDK evaluation cannot provide.

Browser HTTP evaluation

Use browser evaluation only with a Publishable client key with client:evaluate, exact allowed origins, and flags explicitly exposed in that environment.

Browser callers never receive snapshots or targeting rules. They send context to the hosted API and receive only resolved values for flags permitted by exposure checks.

Browser context is controlled by the user. It can shape presentation but cannot prove identity, authorization, billing entitlement, or permission to perform a sensitive operation.

Use more than one approach

One project can use different approaches at different trust boundaries. A server may evaluate locally while a web client uses the hosted endpoint for a small exposed subset.

Keep their keys separate even when they bind to the same environment. Review defaults independently: the safe browser experience may differ from the safe server behaviour.

Avoid evaluating the same consequential decision independently in browser and server code. Let the trusted server own enforcement and use the browser result for presentation only.

Decision checklist

Choose Node.js local evaluation when:

The application is trusted and uses supported Node.js.
Request-time network latency is undesirable.
Bounded configuration staleness is acceptable.
The process can initialize, monitor, refresh, and close a singleton client.

Choose server HTTP when:

The runtime is not supported by a released SDK.
Hosted freshness is required.
A bounded network dependency fits the operation.
Related flags can be batched.

Choose browser HTTP when:

The value is safe for any browser user to inspect.
The flag is explicitly client-exposed.
Exact allowed origins are maintainable.
Trusted server authorization remains separate.

Keep credential boundaries separate

Server runtime keys are secrets. Publishable client keys are safe to embed only because origin and exposure checks restrict their use. Neither credential can manage FeatureGate.

Continue with Evaluation credentials, Node.js SDK, or Evaluate over HTTP.