@guidelytech/flags

中文文档
0.18.0发布于 2026/11/09MITTypeScriptESM + CJS零依赖近 30 天下载 1.4万

TypeScript 的向导特征旗和实验:浏览器,节点.js,Next.js,边缘运行时间

中文使用文档
文档目录9 节
  1. 密钥
  2. 浏览器
  3. 节点.js / 服务器
  4. 下一个.js
  5. 边缘运行时间和无服务器
  6. API 密码
  7. 选项
  8. Dev 覆盖( CI和测试)
  9. 国 际

@ 指导技术/旗子

TypeScript 的向导特征旗帜,远程配置和实验. 一个浏览器客户端, Node.js ~ 18, Next.js (服务器和边缘), Deno, Bun and React Industrial; 没有运行时间依赖性.

如果您已经使用指南 SDK(@guidelytech/react, (中文(简体) ), nextjs, (中文(简体) ), react-native, (中文(简体) ), svelte, (中文(简体) ), sveltekit, (中文(简体) ), sdk-core 或脚本标签),旗帜构建于: guidely.flags, (中文(简体) ), useFlag(), (中文(简体) ), flag()...有身份、页面和设备属性 直接使用此软件包 用于服务器、边缘功能和只使用旗帜的应用程序.

pnpm add @guidelytech/flags

密钥

  • 公用钥匙 pk_… ——您已经用作环境密钥 projectId 用于跟踪。 工程 无处不在,没有其他配置.
  • 密钥 gly_sk_… (范围) flags:read——也需要 environment获取 ,当环境从公共密钥中隐藏规则时工作.

浏览器

import { createFlagsClient } from "@guidelytech/flags";

const flags = createFlagsClient({
  sdkKey: "pk_prod_…",
  apiUrl: "https://guidelytech.com",
  attributes: { id: user.id, plan: user.plan, account: { id: org.id } },
});

await flags.ready();
if (flags.isEnabled("new-checkout")) showNewCheckout();
const color = flags.getString("checkout-button-color", "blue");
flags.subscribe(() => render()); // payload, attribute or override changes
flags.updateAttributes({ plan: "enterprise" });

最后一个有效载荷保存在 localStorage因此,返回的来访者立即获得旗帜,并下线.

节点.js / 服务器

每个进程有一个客户;对每个请求进行评价 forUser() (它永远不会改变客户端):

import { createFlagsClient } from "@guidelytech/flags";

export const flags = createFlagsClient({ sdkKey: process.env.GUIDELY_SDK_KEY!, environment: "production" });

app.get("/checkout", async (req, res) => {
  await flags.ready(); // resolves once, after the first download (or failure)
  const f = flags.forUser({ id: req.user.id, plan: req.user.plan });
  res.render("checkout", { newCheckout: f.isEnabled("new-checkout"), limits: f.getJson("limits", {}) });
});

下一个.js

使用 @guidelytech/nextjs/server (单位:千美元)getFlags(), (中文(简体) ), getFlagsBootstrap(): 它让一个客户横跨 请求和热重装并绕过 Next.js 获取缓存 。 过 getFlagsBootstrap() 页:1 在服务器和客户端上生成相同值的浏览器提供者 .

边缘运行时间和无服务器

当缓存停止时

const flags = createFlagsClient({ sdkKey: "pk_prod_…", pollingMode: "lazy", cacheTtlSeconds: 30 });

API 密码

ready() 编号 : isReady()第一个负载确定( bootstrap, 网络成功或失败) 。 绝不拒绝.
isEnabled(key, fallback = false)只有布尔旗:任何其他值给出 fallback。 。 。 .
getValue(key, fallback)数值,或 fallback 失踪时,无效或属于JSON类型.
getString 编号 : getNumber 编号 : getBoolean 编号 : getJson键入器有相同的规则.
getDetails(key, fallback)数值加 reason, (中文(简体) ), ruleId, (中文(简体) ), variationId, (中文(简体) ), experiment, (中文(简体) ), usedFallback。 。 。 .
getAll()每面旗帜的值(记录不曝光).
forUser(attributes)获取其它属性( 合并到客户端) .
setAttributes 编号 : updateAttributes 编号 : getAttributes替换/ 合并/ 读取属性 .
setOverrides(map | null)当地价值(见 overrideBehaviour) (中文(简体) ).
setOffline(bool) 编号 : refresh()暂停网络活动 / 现在获取 .
getPayload()从服务器渲染中拖出浏览器的有效载荷(或远程结果) .
subscribe(listener)更改通知; 返回 unsubscribe (与 useSyncExternalStore) (中文(简体) ).
flush() 编号 : destroy()现在发送使用/ 停止计时器和流 .

Getters 从不掷出也从不挡道:在旗下加载(或者如果向导无法到达)之前,他们返回 你的后退 以及最后的好载荷.

选项

选项默认
sdkKey (别名) projectId(中文(简体) )—— 说pk_… 或者说 gly_sk_…。 。 。 .
apiUrlhttps://guidelytech.com您的指南 URL .
environment—— 说要求为 gly_sk_ 键.
attributes{}默认属性.
pollingModeautoauto (每个 pollIntervalSeconds,默认为60, lazy (关于 cacheTtlSeconds, (中文(简体) ), manual (单位:千美元)refresh() 仅此而已, stream (服务器出席活动,断开时进行投票).
payload 编号 : remoteResults—— 说靴子:即时使用(ready (一时).
remoteEvalfalse对服务器进行评估( E)POST /flags/evaluate用于隐藏其规则的环境。 当公钥获得时自动打开 remote_evaluation_required。当属性改变时,重新评价(解析出);每个属性集的结果被缓存.
decryptionKey—— 说对于加密的有效载荷(AES-256-GCM通过WebCrypto).
overrides 编号 : overrideBehaviour- / (单位:千美元) localOverRemotelocalOnly (从不取来; 覆盖,然后是靴子) payload, (中文(简体) ), localOverRemote (胜诉), remoteOverLocal (仅用于远程缺失的旗帜).
devOverridestrue读取 dev 覆盖 从环境变量和测试全局.
enableUrlOverridesfalse浏览器 QA : ?guidely_flags=new-checkout:true,checkout-button-color:"green"。 。 。 .
stickyBucketService—— 说InMemoryStickyBucketStore 编号 : LocalStorageStickyBucketStore:用户保留其实验变异.
storagelocalStorage 在浏览器中任意 getItem编号 :setItem 存储、同步或同步. false 禁用 .
trackingCallback(experiment, result)—— 说每(实验,用户,变异)一次:向你的分析仪发送曝光.
trackExposurestrue 除非 trackingCallback向"向导"发送曝光,获取实验结果.
reportUsagetrue合计评价计数,最多为每60人sendBeacon 在页面隐藏中).
onReady, (中文(简体) ), onChange, (中文(简体) ), onFlagEvaluated, (中文(简体) ), onError—— 说钩子.
offline, (中文(简体) ), fetch, (中文(简体) ), logger, (中文(简体) ), now—— 说开始下线; 自定义获取; null 沉默日志; 用于测试的时钟.

createStaticFlags({ payload, attributes }) 在没有网络的有效载荷上给同样的进取器 或跟踪——框架绑定使用它来提供服务器和水合物.

Dev 覆盖( CI和测试)

不触摸应用程序的平子旗值 。 每个客户都读过一次,当它创建时:

来源示例
GUIDELY_FLAG_OVERRIDESnew-checkout:true,limit:5,theme:"dark" 或者说 {"new-checkout":true}
GUIDELY_FLAG_OVERRIDES_FILE路径到持有相同文本的文件( JSON 对象或一个) key:value (每行)
GUIDELY_FLAG_OVERRIDE_BEHAVIOURlocalOnly ——无网络,无缓存有效载荷:隐形试验
globalThis.__GUIDELY_FLAG_OVERRIDES__ 编号 : __GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__对象或同文本,由页面中的测试导师设置
GUIDELY_FLAG_OVERRIDES='new-checkout:true' GUIDELY_FLAG_OVERRIDE_BEHAVIOUR=localOnly pnpm test
GUIDELY_FLAG_OVERRIDES_FILE=ci/flags.json pnpm test

样本 ci/flags.json (键为旗下键;给每个值为旗下类型,因为 类型错误或 null 使受难者返回倒计时:

{
  "new-checkout": true,
  "checkout-button-color": "green",
  "max-cart-items": 25,
  "pricing-page": { "layout": "grid", "plans": ["starter", "pro", "team"] },
  "holiday-banner": null
}
// Playwright: set before the page's scripts run.
await page.addInitScript(() => {
  (window as any).__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true };
});
// Cypress: cy.visit("/", { onBeforeLoad: (win) => { win.__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true }; } });

每旗,后取胜: overrides 编号 : setOverrides() * 文件 · 可变 · 全球 · ?guidely_flags=。 。 。 . setOverrides() 仅取代第一个。 价值有道理 OVERRIDE客户端 日志一个列出使用中的源的警告, 因此生产中设置的变量显示于 日志; 格式错误的源到 onError 并被置之不理. devOverrides: false 关掉它.

使用服务器渲染, 既设置:服务器代码的变量, 也设置浏览器的全局性变量 (反应和Svelte服务器使读取靴子载荷,该载荷没有覆盖). parseOverrides(text) 用于在其它地方读取相同的格式.

国 际

# In CI on your main branch: upload where each flag is used in code (shown on the flag's page).
npx guidely-flags code-refs --key "$GUIDELY_API_KEY" --environment production --repo acme/web

# Debug an evaluation.
npx guidely-flags evaluate --key pk_prod_… --flag new-checkout --attributes '{"id":"u1","plan":"pro"}'

code-refs 需要一个 gly_sk_ 键为 flags:read 财务报告和审定财务报表 flags:code-refs它扫描来自 git ls-files (或散步跳过) node_modules, (中文(简体) ), dist, (中文(简体) ), build, (中文(简体) ), vendor...) 旗下 1 MB 键作为引用的字符串文字写入,并上传 { repo, branch, commit, refs }部门 承诺默认为当前 git 退出( 或 GITHUB_REF_NAME 编号 : GITHUB_SHA) (中文(简体) ). --dry-run 打印参考文献. guidely-flags --help 列出每个选项.

评价语义在 文件/地貌-旗帜-规格.md。 。 。 .

版本与发布记录

@guidelytech/flags 共发布 13 个版本,首次发布于 2026/10/20;过去 12 个月发布了 13 个版本。

版本发布日期距今
0.18.0latest2026/11/098 天前
0.17.02026/11/098 天前
0.16.02026/11/0413 天前
0.15.02026/10/3017 天前
0.14.02026/10/2820 天前
0.13.02026/10/2820 天前

关于 @guidelytech/flags 的常见问题

@guidelytech/flags 是什么?

TypeScript 的向导特征旗和实验:浏览器,节点.js,Next.js,边缘运行时间

如何安装 @guidelytech/flags?

在项目目录运行 npm install @guidelytech/flags,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 guidely-flags,可以用 npx guidely-flags 直接运行。

@guidelytech/flags 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guidelytech/flags 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@guidelytech/flags 可以商用吗?

@guidelytech/flags 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guidelytech/flags 的下载量有多少?

根据 npm 官方下载统计,@guidelytech/flags 在 2026/10/17 – 2026/11/15 这 30 天内被下载 14,353 次,日均约 478 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guidelytech/flags 还在维护吗?

最新版本 0.18.0 发布于 2026/11/09(8 天前);至今共发布 13 个版本,其中过去 12 个月发布了 13 个;首次发布于 2026/10/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。