SDKs

Installation

To install an SDK, see one of the language quickstarts.

Auto-generated, type-safe client

SDKs come with a CLI tool to auto-generate a client so you can access your flags with end-to-end type-safety. This ensures typos in flag names or incorrectly passed targeting attributes can be caught at build-time rather than runtime. It also improves the developer experience with code completion, comments, "find all references" and type-safe flag clean up.

Initialization

You can optionally specify an SDK initialization query to:

• Select which flags to fetch

• Provide some targeting attributes upfront so that any flag logic that depends on those attributes can be partially reduced on the edge

This is useful for:

• Performance

  • You can limit which flags are fetched to reduce the network payload size

  • You can partially reduce flag logic on the edge to:

    • Reduce the network payload size

    • Reduce the logic that needs to be locally evaluated by the SDK

• Security

  • You can eliminate sensitive logic, e.g. a list of user IDs, on the edge so it doesn't get leaked to publicly accessible clients, e.g. in the browser

Build-time fallback snapshot of flag logic

To improve reliability, you can include a fallback snapshot of your flag logic in the generated client at build time. The SDK will instantly initialize from the snapshot first before fetching the latest flag logic from Hypertune Edge.

You can keep the snapshot fresh by setting up a webhook to regenerate the client on every Hypertune commit. In this case, you don't need to initialize from Hypertune Edge at all, eliminating network latency and bandwidth, improving both performance and efficiency.

The snapshot is particularly useful for single-page apps (SPAs) as you can use your flags in the first app render without any page load delay, UI flicker or layout shift.

It also enables using Hypertune in local-only, offline mode, e.g. for running unit tests or in isolated, secure, air-gapped environments.

Hard-coded fallbacks

Whenever you evaluate a flag, you pass a hard-coded fallback value, e.g.

const exampleFlag = hypertune.exampleFlag({ fallback: false });

If Hypertune Edge is unreachable and there's no build-time fallback snapshot of your flag logic, or there's an error evaluating the flag, you'll get this hard-coded fallback value instead.

This ensures that in the worst-case scenario, your app still works properly.

Hydrate or "bootstrap" from your own server

You can hydrate or "bootstrap" the SDK in the browser with the state of the SDK on your server so you can use your flags in the first app render without any page load delay, UI flicker or layout shift.

This works well with server-side rendering frameworks like Next.js, Nuxt, Remix and Gatsby.

Local-only, offline mode

You can disable server initialization and use a build-time fallback snapshot of your flag logic to use SDKs in local-only, offline mode. This is useful for running unit tests or using Hypertune in isolated, secure, air-gapped environments.

Provide targeting attributes

You can define targeting attributes at the:

• root level

• individual flag level

And provide them during:

• SDK initialization

• local flag evaluation

• a mix of both

Typically, you'll provide targeting attributes when locally evaluating the root flag, passing it the context argument you defined in your schema. You'll get back the Root SDK node which will have type-safe methods to evaluate all your individual flags.

You can also provide flag-specific targeting attributes when evaluating individual flags.

Local, synchronous, in-memory flag evaluation

SDKs evaluate flags locally, synchronously, in memory with no network latency. This includes flag logic that contains A/B tests, machine learning loops and analytics event logging.

So you can use an SDK on the backend to evaluate flags, including A/B tests, for different users without adding latency to every request.

And you can use an SDK on the frontend to evaluate flags, including A/B tests, without blocking renders.

Sending logs

SDKs send logs to Hypertune Edge in the background. This allows you to:

• See how often different parts of your flag logic are evaluated, e.g. to see how often different targeting rules are evaluated and passed in realtime

• Log analytics events

• Log split exposures, e.g. for A/B tests, multivariate tests and machine learning loops

• See any SDK errors from the Hypertune UI

You can also manually trigger and wait for logs to be flushed.

Getting flag updates

SDKs listen for updates to your flag logic in the background. When you save and activate a new commit from the Hypertune UI, the SDK will fetch your new flag logic and use it on the next evaluation.

You can also manually trigger and wait for a re-initialization from the server.

And you can add and remove listeners to be notified of updates, e.g. to trigger a re-render on the frontend after an update.

Serverless environments

Hypertune SDKs have been uniquely architected to work optimally in serverless and edge environments like:

• Vercel deployments

• Cloudflare Workers

• AWS Lambdas

• Google Cloud Functions

• Netlify Functions

• DigitalOcean Functions

Vercel Edge Config

If you deploy on Vercel, you can initialize the SDK with near-zero latency in Vercel's edge environment when you set up our Vercel Edge Config integration.

Custom logging

By default, SDKs output info and error logs to the console. But you can provide a custom logging callback to capture and forward logs elsewhere, e.g. to your monitoring infrastructure.

Shutting down

You can shut down an SDK to cleanly stop all its background processes and terminate all its connections.

Git-style version control

You can create branches and configure the SDK and code generation to use a specific branch.