Skip to content

docs: FLAGS_SECRET is optional on Vercel - #596

Draft
luismeyer wants to merge 34 commits into
luismeyer/precompute-deployment-keyfrom
docs/optional-flags-secret
Draft

luismeyer wants to merge 34 commits into
luismeyer/precompute-deployment-keyfrom
docs/optional-flags-secret

Conversation

@luismeyer

@luismeyer luismeyer commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Updates the Flags SDK docs and README so they no longer say a FLAGS_SECRET is required, matching the SDK changes in #586, #587, #589 and #597.

Stacked on #597. Merge after #586 → #587 → #589 → #597, and ship it with the flags release that includes them.

Why

After #586, #587 and #589, an app on Vercel works without a FLAGS_SECRET. encryptFlagValues uses the public key of Vercel, the SDK accepts overrides that Vercel signs, and the discovery endpoint accepts tokens that Vercel signs. After #597, precompute signs its codes with a key that Vercel provides for each deployment. The docs still tell every project to generate and set a secret, and the SvelteKit examples import FLAGS_SECRET from $env/static/private. That import fails the build when the variable isn't defined.

Approach

Describe FLAGS_SECRET as optional on Vercel, and keep it documented where it's still needed:

  • precompute in local development, outside Vercel, with vercel build, or when a code must be valid in another deployment
  • Flags Explorer outside Vercel, or locally without vercel env pull
  • creating your own encrypted overrides, such as in e2e tests

Projects that already have a secret keep working.

Changes

  • packages/flags/README.md (the root README.md links to it): Setup now leads with the no-secret path, and FLAGS_SECRET gets its own optional section.
  • providers/vercel.mdx: drops the line saying activation creates a FLAGS_SECRET that overrides depend on, and drops FLAGS_SECRET from the copy prompt.
  • frameworks/sveltekit/index.mdx: the setup step is now just vc env pull, and createHandle({ flags }) no longer passes a secret.
  • api-reference/frameworks/sveltekit.mdx: createHandle's secret is optional, with the no-secret behavior described.
  • api-reference/frameworks/next.mdx: createFlagsDiscoveryEndpoint works without a secret on Vercel.
  • api-reference/core/core.mdx: verifyAccess accepts Vercel-signed tokens, returns false without a secret, and has a secret param. decryptOverrides verifies Vercel-signed overrides without a secret. The project must expose the system environment variables.
  • frameworks/next/precompute.mdx: precompute works on Vercel without a secret, with the cases that still need one. The precomputation sections of the Next.js and SvelteKit API references have the same note.
  • Both e2e-tests.mdx guides: say the secret is still needed there.

Open points for review

  • Does activating Vercel Flags still create a FLAGS_SECRET per environment? This PR stops saying it does, but doesn't claim it no longer happens.
  • The minimum flags version isn't stated. Add it once the release version is known.
  • Out of scope: skills/flags-sdk, skills/vercel-flags, and the examples/providers/* READMEs and deploy buttons still treat FLAGS_SECRET as required.

Validation

These are docs-only changes, checked against the behavior in the #586, #587, #589 and #597 PR descriptions and changesets, and against packages/flags/src/sveltekit/{index,env}.ts and packages/flags/src/lib/precompute-secret.ts on the #597 branch. I did not build the docs site.

Co-authored-by: vercel-v[bot] <353008837+vercel-v[bot]@users.noreply.github.com>

Co-authored-by: vercel-v[bot] <353008837+vercel-v[bot]@users.noreply.github.com>
@vercel

vercel Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flags-playground Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-dev Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-flagsmith Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-growthbook Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-launchdarkly Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-openfeature Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-posthog Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-reflag Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-snippets Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-statsig Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
flags-sdk-sveltekit-snippets Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
shirt-shop Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC
shirt-shop-api Ready Ready Preview, v0 Nov 17, 2026 4:42pm UTC

luismeyer and others added 2 commits November 11, 2026 11:20
…-secret

Co-Authored-By: Claude Code <noreply@anthropic.com>
…ecryptOverrides

Co-Authored-By: Claude Code <noreply@anthropic.com>
luismeyer and others added 18 commits November 13, 2026 10:42
…s not

Co-Authored-By: Claude Code <noreply@anthropic.com>
…ables

Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
### Prerequisites

Ensure you have a `FLAGS_SECRET` environment variable set. This variable is used by `precompute` to encrypt the precomputation result into the URL. The `FLAGS_SECRET` environment variable is required for precompute to work. It must contain a random string of 32 characters, encoded as Base64.
On Vercel, precompute works without a `FLAGS_SECRET`. The Flags SDK signs the precomputation result with a key that Vercel provides for each deployment, so a code is only valid inside the deployment that created it. In local development (`next dev`) or a local production build (`next build && next start`), it uses a fixed, public secret when there is none, after you run `vercel env pull`. Without a secret, it throws outside of Vercel.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't thinks this is completely correct. Please be more specific that we use a vercel specific env var to determine the env etc.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Ensure you have a `FLAGS_SECRET` environment variable set. This variable is used by `precompute` to encrypt the precomputation result into the URL. The `FLAGS_SECRET` environment variable is required for precompute to work. It must contain a random string of 32 characters, encoded as Base64.
On Vercel, precompute works without a `FLAGS_SECRET`. The Flags SDK signs the precomputation result with a key that Vercel provides for each deployment, so a code is only valid inside the deployment that created it. In local development (`next dev`) or a local production build (`next build && next start`), it uses a fixed, public secret when there is none, after you run `vercel env pull`. Without a secret, it throws outside of Vercel.

You need a `FLAGS_SECRET` environment variable in these cases:

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we can say FLAGS_SECRET or FLAGS_PRECOMPUTE_SECRET here

luismeyer and others added 2 commits November 17, 2026 11:15
…it 3 (#603)

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
… environment

The other variables of Vercel only exist on Vercel, where they are in
process.env. Matches the one variable the docs declare in src/env.ts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch was successfully deployed

14 active deployments
Preview – flags-sdk-dev — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-sveltekit-snippets — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-snippets — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-playground — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-posthog — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-launchdarkly — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-openfeature — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – shirt-shop — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-vercel — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-statsig — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-growthbook — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-reflag — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – flags-sdk-flagsmith — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Preview – shirt-shop-api — b735bdb3 Deployed Nov 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant