> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipthing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch to Hypertune

> How to change the feature flag provider to Hypertune.

[Hypertune](https://www.hypertune.com/) is the most flexible platform for feature flags, A/B testing, analytics and app configuration. Built with full end-to-end type-safety, Git version control and local, synchronous, in-memory flag evaluation. Optimized for TypeScript, React and Next.js.

Here's how to switch your ShipThing project to use Hypertune for feature flags!

## 1. Create a new Hypertune project

Go to Hypertune and create a [new project](https://app.hypertune.com/?new_project=1). Then go to the Settings page of your project and copy the main token.

## 2. Update the environment variables

Update the environment variables across the project. For example:

```js apps/app/.env theme={"system"}
// Add this:
NEXT_PUBLIC_HYPERTUNE_TOKEN=""
```

Add a `.env` file to the `feature-flags` package with the following contents:

```js packages/feature-flags/.env theme={"system"}
NEXT_PUBLIC_HYPERTUNE_TOKEN=""
HYPERTUNE_FRAMEWORK=nextApp
HYPERTUNE_OUTPUT_DIRECTORY_PATH=generated
HYPERTUNE_PLATFORM=vercel
HYPERTUNE_GET_HYPERTUNE_IMPORT_PATH=../lib/getHypertune
```

## 3. Update the `keys.ts` file in the `feature-flags` package

Use the `NEXT_PUBLIC_HYPERTUNE_TOKEN` environment variable in the call to `createEnv`:

```ts packages/feature-flags/keys.ts {6-8,14} theme={"system"}
import { createEnv } from '@t3-oss/env-nextjs';
import { z } from 'zod';

export const keys = () =>
  createEnv({
    client: {
      NEXT_PUBLIC_HYPERTUNE_TOKEN: z.string().min(1),
    },
    server: {
      FLAGS_SECRET: z.string().min(1).optional(),
    },
    runtimeEnv: {
      FLAGS_SECRET: process.env.FLAGS_SECRET,
      NEXT_PUBLIC_HYPERTUNE_TOKEN: process.env.NEXT_PUBLIC_HYPERTUNE_TOKEN,
    },
  });
```

## 4. Swap out the required dependencies

First, delete the `create-flag.ts` file.

Then, uninstall the existing dependencies from the `feature-flags` package:

```sh Terminal theme={"system"}
pnpm remove @repo/analytics --filter @repo/feature-flags
```

Then, install the new dependencies:

```sh Terminal theme={"system"}
pnpm add hypertune server-only --filter @repo/feature-flags
```

## 5. Set up Hypertune code generation

Add `analyze` and `build` scripts to the `package.json` file for the `feature-flags` package, which both execute the `hypertune` command:

```json packages/feature-flags/package.json theme={"system"}
{
  "scripts": {
    "analyze": "hypertune",
    "build": "hypertune"
  }
}
```

Then run code generation with the following command:

```sh Terminal theme={"system"}
pnpm build --filter @repo/feature-flags 
```

This will generate the following files:

```txt theme={"system"}
packages/feature-flags/generated/hypertune.ts
packages/feature-flags/generated/hypertune.react.tsx
packages/feature-flags/generated/hypertune.vercel.tsx
```

## 6. Set up Hypertune client instance

Add a `getHypertune.ts` file in the `feature-flags` package which defines a `getHypertune` function that returns an initialized instance of the Hypertune SDK on the server:

```ts packages/feature-flags/lib/getHypertune.ts theme={"system"}
import 'server-only';
import { auth } from '@repo/auth/server';
import { unstable_noStore as noStore } from 'next/cache';
import type { ReadonlyHeaders } from 'next/dist/server/web/spec-extension/adapters/headers';
import type { ReadonlyRequestCookies } from 'next/dist/server/web/spec-extension/adapters/request-cookies';
import { createSource } from '../generated/hypertune';
import { getVercelOverride } from '../generated/hypertune.vercel';
import { keys } from '../keys';

const hypertuneSource = createSource({
  token: keys().NEXT_PUBLIC_HYPERTUNE_TOKEN,
});

export default async function getHypertune(params?: {
  headers?: ReadonlyHeaders;
  cookies?: ReadonlyRequestCookies;
}) {
  noStore();
  await hypertuneSource.initIfNeeded(); // Check for flag updates

  const { userId, orgId, sessionId } = await auth();

  // Respect flag overrides set by the Vercel Toolbar
  hypertuneSource.setOverride(await getVercelOverride());

  return hypertuneSource.root({
    args: {
      context: {
        environment: process.env.NODE_ENV,
        user: { id: userId ?? '', sessionId: sessionId ?? '' },
        org: { id: orgId ?? '' },
      },
    },
  });
}
```

## 7. Update `index.ts`

Hypertune automatically generates feature flag functions that use the `flags` package. To export them the same way as before, update the `index.ts` file to export everything from the `generated/hypertune.vercel.ts` file:

```ts packages/feature-flags/index.ts theme={"system"}
export * from "./generated/hypertune.vercel.tsx"
```

Hypertune adds a `Flag` suffix to all these generated feature flag functions, so you will need to update flag usages with this, e.g. `showBetaFeature` => `showBetaFeatureFlag`.

## 8. Add more feature flags

To add more feature flags, create them in the Hypertune UI and then re-run code generation. They will be automatically added to your generated files.