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

# 切换到 Hypertune

> 如何将功能标志提供者更改为 Hypertune。

[Hypertune](https://www.hypertune.com/) 是用于功能标志、A/B 测试、分析和应用配置的最灵活的平台。具有完整的端到端类型安全、Git 版本控制以及本地同步的内存标志评估。针对 TypeScript、React 和 Next.js 进行了优化。

以下是如何将您的 ShipThing 项目切换到使用 Hypertune 进行功能标志管理！

## 1. 创建一个新的 Hypertune 项目

访问 Hypertune 并创建一个[新项目](https://app.hypertune.com/?new_project=1)。然后转到项目的设置页面并复制主令牌。

## 2. 更新环境变量

更新整个项目的环境变量。例如:

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

在 `feature-flags` 软件包中添加内容如下的 `.env` 文件:

```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. 更新 `feature-flags` 软件包中的 `keys.ts` 文件

在调用 `createEnv` 时使用 `NEXT_PUBLIC_HYPERTUNE_TOKEN` 环境变量:

```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. 替换所需依赖项

首先，删除 `create-flag.ts` 文件。

然后，从 `feature-flags` 包中卸载现有依赖项：

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

然后，安装新的依赖项：

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

## 5. 设置 Hypertune 代码生成

在 `feature-flags` 包的 `package.json` 文件中添加 `analyze` 和 `build` 脚本，这两个脚本都执行 `hypertune` 命令：

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

然后使用以下命令运行代码生成：

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

这将生成以下文件：

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

## 6. 设置 Hypertune 客户端实例

在 `feature-flags` 包中添加一个 `getHypertune.ts` 文件，该文件定义了一个 `getHypertune` 函数，用于在服务器上返回一个初始化的 Hypertune SDK 实例：

```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. 更新 `index.ts`

Hypertune 会自动生成使用 `flags` 包的功能标志函数。为了像以前一样导出它们，请更新 `index.ts` 文件以从 `generated/hypertune.vercel.ts` 文件中导出所有内容：

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

Hypertune 会为所有这些生成的特征标志函数添加后缀 `Flag`，因此您需要更新标志的用法，例如 `showBetaFeature` => `showBetaFeatureFlag`.

## 8. 添加更多的功能标志

要添加更多特性标志，请在 Hypertune UI 中创建它们，然后重新运行代码生成。它们将自动添加到生成的文件中。