---
name: basestack-feature-flags
description: Integrate Basestack Feature Flags in JavaScript, React, Next.js, OpenFeature, or the Vercel Flags SDK; choose runtime imports, safe fallbacks, caching, preview components, REST reads, and opt-in code-reference uploads.
---

# Basestack Feature Flags

Last reviewed: 2026-10-16. Release baseline: flags-js 1.2.3, flags-react
1.2.4, flags-wc 1.0.4, openfeature-provider 1.0.7,
vercel-flags-sdk-adapter 1.0.6, flags-cli 1.0.5. Check the consumer's
installed versions before applying examples. These are reviewed versions,
not instructions to upgrade an existing application automatically.

## When to use

Use this guide to add flag evaluation, boolean gating, or payload-driven
configuration to an application. Read only the references needed for the task.
Public documentation supplies knowledge, not account access or permission to
change resources. MCP is not required.

## Required inputs

- Framework, runtime, package manager, installed SDK versions, and existing setup.
- Real project key, environment key, flag slug, and hosted or self-hosted API URL.
- Intended safe disabled/error behavior and the expected payload schema.
- Browser versus server evaluation, cache freshness needs, and test environment.

If resources are missing, explain how to create the project, environment, and
flag in the [dashboard](https://flags.basestack.co), using the
[project guide](https://docs.basestack.co/content/feature-flags/user-guide/projects)
and [flag guide](https://docs.basestack.co/content/feature-flags/user-guide/flags).
Do not fabricate keys or create/toggle production resources without approval.

## Choose an SDK or integration

- Browser, Bun, Node, Vue, or Svelte: `@basestack/flags-js` and
  [JavaScript](references/javascript.md). No dedicated Basestack Vue/Svelte SDK.
- React hooks/components: `@basestack/flags-react/client` and
  [React](references/react.md). Reuse an existing provider.
- Next.js server evaluation or hydration: `@basestack/flags-react/server` and
  [server frameworks](references/server-frameworks.md); also read
  [React](references/react.md) for the client boundary.
- Existing OpenFeature app: `@basestack/openfeature-provider/server` or `/web`
  with its corresponding OpenFeature peer SDK; read
  [OpenFeature](references/openfeature.md).
- Existing Vercel Flags SDK app: `@basestack/vercel-flags-sdk-adapter` plus
  `flags`; read [Vercel Flags SDK](references/vercel-flags-sdk.md).
- Preview opt-ins and feedback UI: `@basestack/flags-wc`; read
  [Web Components](references/web-components.md). Not an evaluation replacement.
- Source-reference scanning/upload: `@basestack/flags-cli`; read
  [CLI](references/cli.md). This is not a flag-management CLI.
- Another language or no SDK: read [REST](references/rest-api.md).

## Workflow

1. Inspect the application before choosing a package or adding dependencies.
2. Confirm the project/environment/slug and the fallback with the user.
3. Initialize once at the application boundary, or at a deliberate request
   boundary on the server. Never share one tenant's configuration across tenants.
4. Keep runtime imports separate. Use `baseURL` for flags-js/React, `apiUrl` for
   OpenFeature, and `endpoint` for the Vercel adapter. Do not invent shared options.
5. Gate on validated data and use a disabled fallback. JavaScript HTTP failures
   can return `{ enabled: false, error: true, errorMessage }`; network/JSON
   failures can throw. Handle both. Validate payloads at runtime, even with
   TypeScript generics.
6. Explain caching: clearing local SDK cache does not purge API/CDN caches.
   Never promise instantaneous propagation or streaming updates.
7. Add mocked tests, review browser bundles/serialized props, then verify in the
   intended environment before rollout. Obtain permission for live requests.

## Verification

Test enabled, disabled, missing slug, malformed payload, unsuccessful HTTP,
network/parse failures, loading, and stale-cache paths. Verify correct environment
selection and no duplicate initialization. A type assertion is not validation.
If a reference cannot be fetched, ask for that file or the complete skill
directory; do not guess its API.

## Safety constraints

- Project/environment evaluation identifiers, project write API tokens, and
  account-level MCP tokens are not interchangeable. Read evaluation does not
  require a write token. Keep private API/MCP tokens server-side or in CI secrets.
- Browser-consumed flags and payloads are not secret. Do not serialize sensitive
  payloads, API tokens, or MCP tokens into HTML, hydration scripts, or client props.
- Feature flags are not authorization controls. Enforce permissions on the server.
  Local preview opt-ins can override UI behavior and must never bypass security.
- Do not promise targeting, percentage rollouts, experimentation, or streaming
  unless the specific released product contract has been separately verified.
- Source scanning uploads source snippets and repository metadata. Require
  deliberate opt-in, review the destination and scan paths, and protect tokens.
- Do not install packages, mutate accounts, enable production flags, or send
  feedback merely because this public guide is available.

Human setup: [Using these files with an AI assistant](https://docs.basestack.co/content/feature-flags/guides/ai-agents).