# 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.

> [!IMPORTANT] 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](/docs/evaluate/credentials),
[Node.js SDK](/docs/sdk/node), or [Evaluate over HTTP](/docs/evaluate/http-evaluation).