diff --git a/.changeset/browser-framework-collection-values.md b/.changeset/browser-framework-collection-values.md new file mode 100644 index 000000000..56e2af6aa --- /dev/null +++ b/.changeset/browser-framework-collection-values.md @@ -0,0 +1,19 @@ +--- +"@reflag/browser-sdk": major +"@reflag/react-sdk": major +"@reflag/vue-sdk": major +--- + +Adopt protocol-v2, adding support for multivariate and JSON flags in Browser, React and Vue. + +- Browser `getFlag()` and React `useFlag()` return direct values instead of flag wrappers. Vue `useFlag()` returns a ref to the direct value. Replace `.isEnabled` and `.config` access with direct values, using `.value` for Vue refs in script. +- Reads without a default return Booleans, using `false` when unavailable. Pass a positional default to read strings, numbers, arrays, or objects, with TypeScript inferring the return type. Missing values or values of a different top-level type use the default. Pass `null` to accept any JSON value, including null. Nested payload schemas are not validated at runtime. +- React and Vue's optional `Flags` registration checks non-null defaults against each flag's value type, including React Suspense reads. Named-interface and readonly defaults are supported across Browser, React and Vue without losing their inferred value types. +- React `useFlag()` never suspends. Replace `useFlag(key, { suspense: true })` with `useFlagSuspense(key)` to wait for initialization. Use `useIsLoading()` for loading state; existing provider and `useOptInFlags` Suspense options continue to control opt-in loading only. +- Flag reads automatically record checks. Replace flag-level `.track()` and `.requestFeedback()` calls with the client's separate methods or the framework's tracking and feedback hooks/composables. +- Browser `getFlags()` returns a record of direct values; unavailable flags may be `undefined`. Use `getFlagResults()` for diagnostic access without recording checks. +- Bootstrap data must come from Node SDK v2 and be consumed by matching v2 SDKs. Legacy v1 payloads are incompatible. Replace the Browser client's `bootstrappedFlags` option with `bootstrappedState` and pass the complete bootstrap payload. +- Overrides accept direct JSON values: `undefined` clears an override, while `null` is a value. Saved v1 caches and overrides are not reused. +- Bootstrapped clients load opt-in metadata when requested, without replacing server-provided flag values. Successful opt-in changes update both membership and flag values. + +The OpenFeature Browser provider continues to use Browser SDK v1. Legacy remote configuration is not automatically converted into multivariate flag values. diff --git a/.changeset/pre.json b/.changeset/pre.json new file mode 100644 index 000000000..6b485828e --- /dev/null +++ b/.changeset/pre.json @@ -0,0 +1,25 @@ +{ + "mode": "pre", + "tag": "next", + "initialVersions": { + "@reflag/browser-sdk": "2.0.0-next.0", + "@reflag/cli": "1.0.4", + "@reflag/flag-evaluation": "2.0.0", + "@reflag/management-sdk": "0.1.0", + "customer-admin-panel": "0.0.1", + "@reflag/node-sdk": "2.0.0-next.0", + "@reflag/openfeature-browser-provider": "1.3.17", + "nextjs-openfeature-example": "0.2.0", + "@reflag/openfeature-node-provider": "1.2.8", + "@reflag/react-native-sdk": "2.0.0-next.0", + "reflag-react-native-sdk-bare-rn": "0.0.0", + "reflag-react-sdk-expo": "0.0.0", + "@reflag/react-sdk": "2.0.0-next.0", + "nextjs-bootstrap-demo": "0.2.0", + "nextjs-flag-demo": "0.2.0", + "@reflag/rest-api-sdk": "0.0.6", + "@reflag/tsconfig": "0.0.2", + "@reflag/vue-sdk": "2.0.0-next.0" + }, + "changesets": [] +} diff --git a/.changeset/react-native-collection-values.md b/.changeset/react-native-collection-values.md new file mode 100644 index 000000000..b15368c15 --- /dev/null +++ b/.changeset/react-native-collection-values.md @@ -0,0 +1,17 @@ +--- +"@reflag/react-native-sdk": major +--- + +Adopt protocol-v2, adding support for multivariate and JSON flags in React Native. + +- `useFlag()` returns direct values instead of flag wrappers. Reads without a default return Booleans, using `false` when unavailable. Replace `.isEnabled` and `.config` access with direct values. +- Pass a positional default to read strings, numbers, arrays, or objects, with TypeScript inferring the return type. Missing values or values of a different top-level type use the default. Pass `null` to accept any JSON value, including null. Nested payload schemas are not validated at runtime. +- `useFlag()` never suspends. Replace `useFlag(key, { suspense: true })` with `useFlagSuspense(key)` to wait for initialization, and use `useIsLoading()` for loading state. +- Flag reads automatically record checks. Replace flag-level tracking and feedback methods with `useTrack()` and `useSendFeedback()`, using your own Native feedback UI. +- Optional flag typing uses React's `Flags` registration in `@reflag/react-sdk`. Non-null defaults are checked against each registered flag's value type, and named-interface and readonly defaults are supported. Regenerate legacy wrapper-shaped declarations before upgrading. +- Bootstrap data must come from Node SDK v2. Pass the complete payload to `ReflagBootstrappedProvider`; legacy v1 payloads are incompatible. +- AsyncStorage persistence, native live updates and custom storage/SSE adapters remain supported. Live updates are enabled by default; the web toolbar and automatic feedback UI are disabled by default. +- Offline fallbacks accept direct JSON value maps. Arrays of enabled Boolean flag keys remain supported. +- Requires React 17 or later, compatible with your React Native runtime, and matching v2 React/Browser SDKs. + +Legacy wrapper and remote-config types are removed. Legacy remote configuration is not automatically converted into multivariate flag values. diff --git a/.github/workflows/package-ci.yml b/.github/workflows/package-ci.yml index b7e547094..758e4388c 100644 --- a/.github/workflows/package-ci.yml +++ b/.github/workflows/package-ci.yml @@ -29,6 +29,8 @@ jobs: - name: Restore package.json # This step is necessary because the previous step may have updated package.json run: git checkout -- package.json packages/*/package.json + - name: Check release channel safeguards + run: yarn test:release - name: Install Playwright Browsers run: yarn playwright install --with-deps working-directory: ./packages/browser-sdk diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 6bf5ee371..33513380c 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -30,6 +30,9 @@ jobs: scope: "@reflag" - name: Install dependencies run: yarn install --immutable + - name: Determine release channel + id: release-channel + run: node scripts/release-channel.mjs >> "$GITHUB_OUTPUT" - name: Create release PR or publish packages id: changesets uses: changesets/action@v1 @@ -41,22 +44,22 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.CHANGESETS_BOT_TOKEN }} - name: Build docs - if: steps.changesets.outputs.published == 'true' + if: steps.changesets.outputs.published == 'true' && steps.release-channel.outputs.prerelease == 'false' run: yarn docs - name: Checkout docs with SSH - if: steps.changesets.outputs.published == 'true' - uses: actions/checkout@v3 + if: steps.changesets.outputs.published == 'true' && steps.release-channel.outputs.prerelease == 'false' + uses: actions/checkout@v4 with: repository: reflagcom/docs ssh-key: ${{ secrets.DOCS_DEPLOY_KEY }} path: reflag-docs - name: Copy generated docs to docs repo - if: steps.changesets.outputs.published == 'true' + if: steps.changesets.outputs.published == 'true' && steps.release-channel.outputs.prerelease == 'false' run: | rm -rf reflag-docs/sdk cp -R dist/docs reflag-docs/sdk - name: Commit and push changes - if: steps.changesets.outputs.published == 'true' + if: steps.changesets.outputs.published == 'true' && steps.release-channel.outputs.prerelease == 'false' run: | cd reflag-docs git config user.name "github-actions[bot]" diff --git a/.gitignore b/.gitignore index 0d520eb65..c1ebb6abd 100644 --- a/.gitignore +++ b/.gitignore @@ -31,7 +31,7 @@ playwright-report/ playwright/.cache/ .pnp.* -.yarn +.yarn/* !.yarn/patches !.yarn/plugins !.yarn/releases diff --git a/.yarn/patches/@changesets-assemble-release-plan-npm-6.0.9-e01af97ef4.patch b/.yarn/patches/@changesets-assemble-release-plan-npm-6.0.9-e01af97ef4.patch new file mode 100644 index 000000000..37e626949 --- /dev/null +++ b/.yarn/patches/@changesets-assemble-release-plan-npm-6.0.9-e01af97ef4.patch @@ -0,0 +1,70 @@ +diff --git a/dist/changesets-assemble-release-plan.cjs.js b/dist/changesets-assemble-release-plan.cjs.js +index e07ba6e793021b6cfdec898afca517e293386ddb..7b5839bb19d64c0520a826972d4becc05a0a3b12 100644 +--- a/dist/changesets-assemble-release-plan.cjs.js ++++ b/dist/changesets-assemble-release-plan.cjs.js +@@ -518,10 +518,17 @@ snapshot) { + } + if ((preInfo === null || preInfo === void 0 ? void 0 : preInfo.state.mode) === "exit") { + for (let pkg of packages.packages) { ++ if (shouldSkipPackage.shouldSkipPackage(pkg, { ++ ignore: refinedConfig.ignore, ++ allowPrivatePackages: refinedConfig.privatePackages.version ++ })) { ++ continue; ++ } ++ const preVersion = preInfo.preVersions.get(pkg.packageJson.name); + // If a package had a prerelease, but didn't trigger a version bump in the regular release, + // we want to give it a patch release. + // Detailed explanation at https://github.com/changesets/changesets/pull/382#discussion_r434434182 +- if (preInfo.preVersions.get(pkg.packageJson.name) !== 0) { ++ if (preVersion != null && preVersion !== 0) { + const existingRelease = releases.get(pkg.packageJson.name); + if (!existingRelease) { + releases.set(pkg.packageJson.name, { +diff --git a/dist/changesets-assemble-release-plan.esm.js b/dist/changesets-assemble-release-plan.esm.js +index ea2be567403c4ef94a65f3218ccb683cf5cb4bc1..da2fcd125f7a4bb691016e6959156b94eed68edd 100644 +--- a/dist/changesets-assemble-release-plan.esm.js ++++ b/dist/changesets-assemble-release-plan.esm.js +@@ -507,10 +507,17 @@ snapshot) { + } + if ((preInfo === null || preInfo === void 0 ? void 0 : preInfo.state.mode) === "exit") { + for (let pkg of packages.packages) { ++ if (shouldSkipPackage(pkg, { ++ ignore: refinedConfig.ignore, ++ allowPrivatePackages: refinedConfig.privatePackages.version ++ })) { ++ continue; ++ } ++ const preVersion = preInfo.preVersions.get(pkg.packageJson.name); + // If a package had a prerelease, but didn't trigger a version bump in the regular release, + // we want to give it a patch release. + // Detailed explanation at https://github.com/changesets/changesets/pull/382#discussion_r434434182 +- if (preInfo.preVersions.get(pkg.packageJson.name) !== 0) { ++ if (preVersion != null && preVersion !== 0) { + const existingRelease = releases.get(pkg.packageJson.name); + if (!existingRelease) { + releases.set(pkg.packageJson.name, { +diff --git a/src/index.ts b/src/index.ts +index c8038f0b2447d443f56d42b6e1746270979ce894..d062e71db5b47e8be663f7dc449e33f6a70c27d7 100644 +--- a/src/index.ts ++++ b/src/index.ts +@@ -213,9 +213,18 @@ function assembleReleasePlan( + if (preInfo?.state.mode === "exit") { + for (let pkg of packages.packages) { ++ if ( ++ shouldSkipPackage(pkg, { ++ ignore: refinedConfig.ignore, ++ allowPrivatePackages: refinedConfig.privatePackages.version, ++ }) ++ ) { ++ continue; ++ } ++ const preVersion = preInfo.preVersions.get(pkg.packageJson.name); + // If a package had a prerelease, but didn't trigger a version bump in the regular release, + // we want to give it a patch release. + // Detailed explanation at https://github.com/changesets/changesets/pull/382#discussion_r434434182 +- if (preInfo.preVersions.get(pkg.packageJson.name) !== 0) { ++ if (preVersion != null && preVersion !== 0) { + const existingRelease = releases.get(pkg.packageJson.name); + if (!existingRelease) { + releases.set(pkg.packageJson.name, { diff --git a/package.json b/package.json index f322f1b86..be7b818d8 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,7 @@ "dev": "lerna run dev --parallel", "build": "lerna run build --stream", "test:ci": "lerna run test:ci --stream", + "test:release": "node --test scripts/release-channel.test.mjs", "test": "lerna run test --stream", "format": "yarn fmt:fix && yarn lint:fix", "lint": "yarn oxlint .", @@ -31,6 +32,7 @@ }, "devDependencies": { "@changesets/cli": "^2.29.6", + "@changesets/get-release-plan": "^4.0.15", "husky": "^9.1.7", "lerna": "^10.1.1", "lint-staged": "^16.2.7", @@ -45,6 +47,7 @@ "typescript": "^5.7.3" }, "resolutions": { + "@changesets/assemble-release-plan@npm:^6.0.9": "patch:@changesets/assemble-release-plan@npm%3A6.0.9#~/.yarn/patches/@changesets-assemble-release-plan-npm-6.0.9-e01af97ef4.patch", "minimatch@npm:9.0.1": "npm:9.0.9", "postcss@npm:8.4.31": "npm:8.5.32", "postcss@npm:~8.4.32": "npm:8.5.32", diff --git a/packages/browser-sdk/README.md b/packages/browser-sdk/README.md index dc09ae510..24c2f1153 100644 --- a/packages/browser-sdk/README.md +++ b/packages/browser-sdk/README.md @@ -1,591 +1,184 @@ # Reflag Browser SDK -Basic client for [Reflag.com](https://reflag.com). If you're using React, you'll be better off with the Reflag React SDK. +Feature flags, remote configuration, usage tracking and feedback for browser applications. -Reflag supports flag toggling, tracking flag usage, [collecting feedback](#qualitative-feedback-on-beta-flags) on flags, and [remotely configuring flags](#remote-config). +## Get started -## Install +### 1. Create a client -First find your `publishableKey` under [environment settings](https://app.reflag.com/env-current/settings/app-environments) in Reflag. +Install the SDK: -The package can be imported or used directly in a HTML script tag: - -A. Import module: - -```typescript -import { ReflagClient } from "@reflag/browser-sdk"; - -const user = { - id: 42, - role: "manager", -}; - -const company = { - id: 99, - plan: "enterprise", -}; - -const reflagClient = new ReflagClient({ publishableKey, user, company }); - -await reflagClient.initialize(); - -const { - isEnabled, - config: { payload: question }, - track, - requestFeedback, -} = reflagClient.getFlag("huddle"); - -if (isEnabled) { - // Show flag. When retrieving `isEnabled` the client automatically - // sends a "check" event for the "huddle" flag which is shown in the - // Reflag UI. - - // On usage, call `track` to let Reflag know that a user interacted with the flag - track(); - - // The `payload` is a user-supplied JSON in Reflag that is dynamically picked - // out depending on the user/company. - const question = payload?.question ?? "Tell us what you think of Huddles"; - - // Use `requestFeedback` to create "Send feedback" buttons easily for specific - // flags. This is not related to `track` and you can call them individually. - requestFeedback({ title: question }); -} - -// `track` just calls `reflagClient.track()` to send an event using the same flag key -// You can also use `track` on the client directly to send any custom event. -reflagClient.track("huddle"); - -// similarly, `requestFeedback` just calls `reflagClient.requestFeedback({flagKey: })` -// which you can also call directly: -reflagClient.requestFeedback({ flagKey: "huddle" }); -``` - -B. Script tag (client-side directly in html) - -See [example/browser.html](https://github.com/reflagcom/javascript/tree/main/packages/browser-sdk/example/browser.html) for a working example: - -```html - - -Loading... - +```sh +npm install @reflag/browser-sdk ``` -### Init options - -Supply these to the constructor call: - -```typescript -type Configuration = { - logger: console; // by default only logs warn/error, by passing `console` you'll log everything - apiBaseUrl?: "https://front.reflag.com"; - credentials?: "include" | "same-origin" | "omit"; // forwarded to fetch requests; "include" also enables credentials for the default EventSource transport - feedback?: undefined; // See FEEDBACK.md - enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Reflag servers. Useful when you're impersonating a user - enableLiveFlagUpdates?: false; // Set to `true` to keep flags up to date over SSE (browser SDK default: false) - eventSourceFactory?: (url: string) => { - // Advanced: provide a custom EventSource-compatible transport - addEventListener: (type: string, cb: (event: any) => void) => void; - close: () => void; - }; - fallbackFlags?: - | string[] - | Record; // Enable these flags if unable to contact reflag.com. Can be a list of flag keys or a record with configuration values - timeoutMs?: number; // Timeout for fetching flags (default: 5000ms) - staleWhileRevalidate?: boolean; // Revalidate in the background when cached flags turn stale to avoid latency in the UI (default: false) - staleTimeMs?: number; // at initialization time flags are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase this in the case of a non-SPA - expireTimeMs?: number; // In case we're unable to fetch flags from Reflag, cached/stale flags will be used instead until they expire after `expireTimeMs`. Default is 30 days - offline?: boolean; // Use the SDK in offline mode. Offline mode is useful during testing and local development -}; -``` - -## Migrating from Bucket SDK - -If you have been using the Bucket SDKs, the following list will help you migrate to Reflag SDK: - -- `Bucket*` classes, and types have been renamed to `Reflag*` (e.g. `BucketClient` is now `ReflagClient`) -- `Feature*` classes, and types have been renamed to `Feature*` (e.g. `Feature` is now `Flag`, `RawFeatures` is now `RawFlags`) -- All methods that contained `feature` in the name have been renamed to use the `flag` terminology (e.g. `getFeature` is `getFlag`) -- The `fallbackFeatures` property in client constructor and configuration files has been renamed to `fallbackFlags` -- `featureKey` has been renamed to `flagKey` in all methods that accepts that argument -- The new cookies that are stored in the client's browser are now `reflag-*` prefixed instead og `bucket-*` -- The `featuresUpdated` hook has been renamed to `flagsUpdated` -- The `checkIsEnabled` and `checkConfig` hooks have been removed, use `check` from now on - -To ease in transition to Reflag SDK, some of the old methods have been preserved as aliases to the new methods: - -- `getFeature` method is an alias for `getFlag` -- `getFeatures` method is an alias for `getFlags` -- `featuresUpdated` hook is an alias for `flagsUpdated` - -If you are running with strict Content Security Policies active on your website, you will need change them as follows: - -- `connect-src https://front.bucket.co` to `connect-src https://front.reflag.com` - -Finally, if you have customized the look & feel of the Feedback component, update `--bucket-feedback-*` CSS classes to `--reflag-feedback-*` - -## Flag toggles - -Reflag determines which flags are active for a given user/company. The user/company is given in the ReflagClient constructor. - -If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety. -In addition to the `id`, you must also supply anything additional that you want to be able to evaluate flag targeting rules against. - -Attributes cannot be nested (multiple levels) and must be either strings, integers or booleans. -Some attributes are special and used in Reflag UI: - -- `name` -- display name for `user`/`company`, -- `email` -- is accepted for `user`s and will be highlighted in the Reflag UI if available, -- `avatar` -- can be provided for both `user` and `company` and should be an URL to an image. +Create a client with your **publishable** key and the signed-in user's context: ```ts -const reflagClient = new ReflagClient({ - publishableKey, - user: { - id: "user_123", - name: "John Doe", - email: "john@acme.com" - avatar: "https://example.com/images/udsy6363" - }, - company: { - id: "company_123", - name: "Acme, Inc", - avatar: "https://example.com/images/31232ds" - }, -}); -``` - -To retrieve flags along with their targeting information, use `getFlag(key: string)`: - -```ts -const huddle = reflagClient.getFlag("huddle"); -// { -// isEnabled: true, -// config: { key: "zoom", payload: { ... } }, -// track: () => Promise -// requestFeedback: (options: RequestFeedbackData) => void -// } -``` - -You can use `getFlags()` to retrieve all enabled flags currently. +import { ReflagClient } from "@reflag/browser-sdk"; -```ts -const flags = reflagClient.getFlags(); -// { -// huddle: { -// isEnabled: true, -// targetingVersion: 42, -// config: ... -// } -// } +const reflag = new ReflagClient({ + publishableKey: "your-publishable-key", + user: { id: "alice", role: "manager" }, + company: { id: "acme", plan: "enterprise" }, +}); +await reflag.initialize(); ``` -`getFlags()` is meant to be more low-level than `getFlag()` and it typically used -by down-stream clients, like the React SDK. +Publishable keys are safe to ship to the browser. Keep secret keys on your server. -Note that accessing `isEnabled` on the object returned by `getFlags` does not automatically -generate a `check` event, contrary to the `isEnabled` property on the object returned by `getFlag`. +### 2. Create a flag -## End-user opt-in +Create a flag with the key `huddles` in the Reflag app. -If a flag has end-user opt-in enabled in Reflag, you can list the opt-in options for the current context and set or cancel opt-in for the current user or company. +### 3. Read the flag ```ts -const optInFlags = reflagClient.getOptInFlags(); -// [{ key, name, description, isEnabled, userOptedIn, companyOptedIn, isOptedIn }] - -try { - const response = await reflagClient.setOptIn("huddle", { - optedIn: true, // Use false to cancel this scope's opt-in. - scope: "user", // Use "company" to change the current company's opt-in. - }); - if (!response?.ok) { - console.error("Could not update opt-in"); - } -} catch (error) { - console.error("Could not update opt-in", error); +if (reflag.getFlag("huddles")) { + await reflag.track("Started huddle"); } ``` -By default, `setOptIn()` changes the opt-in for the current user, so the current context must include a `user.id`. To manage the current company's opt-in instead, pass `scope: "company"`; the context must then include a `company.id`. - -User and company opt-ins are managed independently. Setting `optedIn` to `false` removes the opt-in only for the selected scope. For example, cancelling a user's opt-in does not change the company's opt-in for the same flag. - -`setOptIn` returns a promise so you can wait for the new membership state to be synchronized. On success, it resolves after the refreshed flag state has been applied locally, the requested membership change has been confirmed, and `flagsUpdated` listeners have been notified when flags change. - -The promise resolves to a `Response`, or `undefined` if skipped due to invalid input, offline mode etc. Check `response?.ok` for success. - -The `description` comes from the dedicated SDK-facing opt-in description configured in Reflag. +## Read flags -When using bootstrapped flags, the first `getOptInFlags()` or `getIsLoadingOptInFlags()` call requests a flags refresh. The list call returns the currently available list synchronously, and the loading getter returns `true` until that refresh succeeds or fails. Normal initialization also exposes loading through the client's state. - -Listen for `optInFlagsLoadingUpdated` to update UI when this loading state changes. `flagsUpdated` is emitted when a successful refresh updates the list. - -If fetching opt-in metadata fails, loading ends without exposing an error. Call `reflagClient.refresh()` to retry. - -## Remote config - -Remote config is a dynamic and flexible approach to configuring flag behavior outside of your app – without needing to re-deploy it. - -Similar to `isEnabled`, each flag has a `config` property. This configuration is managed from within Reflag. -It is managed similar to the way access to flags is managed, but instead of the binary `isEnabled` you can have -multiple configuration values which are given to different user/companies. +Pass a flag key to check whether the flag is enabled: ```ts -const flags = reflagClient.getFlags(); -// { -// huddle: { -// isEnabled: true, -// targetingVersion: 42, -// config: { -// key: "gpt-3.5", -// payload: { maxTokens: 10000, model: "gpt-3.5-beta1" } -// } -// } -// } -``` - -`key` is mandatory for a config, but if a flag has no config or no config value was matched against the context, the `key` will be `undefined`. Make sure to check against this case when trying to use the configuration in your application. `payload` is an optional JSON value for arbitrary configuration needs. - -Just as `isEnabled`, accessing `config` on the object returned by `getFlags` does not automatically -generate a `check` event, contrary to the `config` property on the object returned by `getFlag`. - -## Server-side rendering and bootstrapping - -For server-side rendered applications, you can render immediately with pre-fetched flag data by bootstrapping the client. - -### Init options bootstrapped - -```typescript -type Configuration = { - logger: console; // by default only logs warn/error, by passing `console` you'll log everything - apiBaseUrl?: "https://front.reflag.com"; - credentials?: "include" | "same-origin" | "omit"; // forwarded to fetch requests; "include" also enables credentials for the default EventSource transport - feedback?: undefined; // See FEEDBACK.md - enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Reflag servers. Useful when you're impersonating a user - offline?: boolean; // Use the SDK in offline mode. Offline mode is useful during testing and local development - bootstrappedState?: { - context: ReflagContext; - flags: FetchedFlags; - flagStateVersion?: number; - }; // Pre-fetched evaluated state from server-side (see Server-side rendering section) - bootstrappedFlags?: FetchedFlags; // Deprecated: use `bootstrappedState` instead -}; +const enabled = reflag.getFlag("huddles"); // true or false ``` -### Using `bootstrappedState` +To read a configuration value, pass a default as the second argument. You get back a value of the same type as the default: -Use the Node SDK's `getFlagsForBootstrap()` method to pre-fetch evaluated state server-side, then pass the returned object directly to the browser client: - -```typescript -// Server-side: Get bootstrapped state using Node SDK -import { ReflagClient as ReflagNodeClient } from "@reflag/node-sdk"; - -const serverClient = new ReflagNodeClient({ secretKey: "your-secret-key" }); -await serverClient.initialize(); - -const bootstrappedState = serverClient.getFlagsForBootstrap({ - user: { id: "user123", name: "John Doe", email: "john@acme.com" }, - company: { id: "company456", name: "Acme Inc", plan: "enterprise" }, -}); - -// Pass the bootstrapped state to the client using your framework's preferred method -app.get("/", (req, res) => { - res.set("Content-Type", "text/html"); - res.send( - Buffer.from( - ` -
`, - ), - ); -}); - -// Client-side: Initialize with pre-fetched evaluated state -import { ReflagClient } from "@reflag/browser-sdk"; - -const reflagClient = new ReflagClient({ - publishableKey: "your-publishable-key", - bootstrappedState, // Contains context, flags, and optional flagStateVersion -}); - -await reflagClient.initialize(); -const { isEnabled } = reflagClient.getFlag("huddle"); +```ts +const model = reflag.getFlag("model", "quick"); // string +const settings = reflag.getFlag("assistant-settings", { model: "quick" }); // { model: string } ``` -The `bootstrappedState` object contains: +If the flag doesn't exist, or its value has a different type, you get `false`, or your default if you passed one. Pass `null` as the default to accept any JSON value and narrow it yourself. -- `context`: the evaluation context used on the server -- `flags`: the evaluated raw flags -- `flagStateVersion`: an optional version used to avoid redundant live-update refreshes immediately after bootstrapping +The SDK checks only the top-level type of a value. If your application depends on nested fields, validate them. -If you want live flag updates to continue working after bootstrapping, use a recent `@reflag/node-sdk` so `getFlagsForBootstrap()` includes `flagStateVersion`. +`getFlags()` returns all flag values as a record. -If a bootstrapped application requests opt-in flags, the browser SDK performs one flags refresh. Applications that do not request opt-in data do not make this request. +Each read records a check, which Reflag uses for launch monitoring. -If you previously used `bootstrappedFlags`, migrate like this: +## Track usage and feedback -```typescript -// Before -const { flags } = serverClient.getFlagsForBootstrap(context); -const client = new ReflagClient({ - publishableKey, - user: context.user, - company: context.company, - other: context.other, - bootstrappedFlags: flags, -}); - -// After -const bootstrappedState = serverClient.getFlagsForBootstrap(context); -const client = new ReflagClient({ - publishableKey, - bootstrappedState, -}); +```ts +await reflag.track("Started huddle", { button: "cta" }); +reflag.requestFeedback({ flagKey: "huddles", title: "How did it go?" }); +await reflag.feedback({ flagKey: "huddles", score: 5 }); ``` -> [!NOTE] -> After bootstrapping, any live flag updates are fetched directly by the browser SDK from Reflag using the browser-visible context. If your bootstrapped snapshot depends on server-only or secret context that is not available in the browser, later live refreshes may differ. In that case, keep `enableLiveFlagUpdates` disabled. -> -> Requesting opt-in flags also triggers a browser-side refresh, even when `enableLiveFlagUpdates` is disabled. - -This eliminates loading states and removes the initial render's dependency on the flags API. +`requestFeedback()` opens the feedback form. `feedback()` sends feedback you collected yourself. -## Context management +Configure your flag's adoption rules to match the event names you send. See [FEEDBACK.md](./FEEDBACK.md) to configure feedback prompts and the feedback UI. -### Updating user/company/other context - -Attributes given for the user/company/other context in the ReflagClient constructor can be updated for use in flag targeting evaluation with the `updateUser()`, `updateCompany()` and `updateOtherContext()` methods. -They return a promise which resolves once the flags have been re-evaluated follow the update of the attributes. - -> [!NOTE] > `user`/`company` attributes are also stored remotely on the Reflag servers and will automatically be used to evaluate flag targeting if the page is refreshed. - -### setContext() - -The `setContext()` method allows you to replace the entire context (user, company, and other attributes) at once. This method is useful when you need to completely change the context, such as when a user logs in or switches between different accounts. +## Update context ```ts -await reflagClient.setContext({ - user: { - id: "new-user-123", - name: "Jane Doe", - email: "jane@example.com", - role: "admin", - }, - company: { - id: "company-456", - name: "New Company Inc", - plan: "enterprise", - }, - other: { - feature: "beta", - locale: "en-US", - }, +await reflag.updateUser({ role: "admin" }); +await reflag.updateCompany({ plan: "enterprise" }); +await reflag.updateOtherContext({ region: "eu" }); + +// Replace the whole context, for example after the user switches company: +await reflag.setContext({ + user: { id: "bob" }, + company: { id: "other-company" }, }); ``` -The method will: +The update methods merge into their section of the context, while `setContext()` replaces all of it. User and company sections need an `id`. Flag values are refetched for the new context. -- Replace the entire context with the new values -- Re-evaluate all flags based on the new context -- Update the user and company information on Reflag servers -- Return a promise that resolves once the flags have been re-evaluated +## Bootstrap from the server -### getContext() - -The `getContext()` method returns the current context being used for flag evaluation. This is useful for debugging or when you need to inspect the current user, company, and other attributes. +To render flags immediately, without waiting for a network request, evaluate them on your server with the **Node.js SDK** and pass the result to the browser: ```ts -const currentContext = reflagClient.getContext(); -console.log(currentContext); -// { -// user: { id: "user-123", name: "John Doe", email: "john@example.com" }, -// company: { id: "company-456", name: "Acme Inc", plan: "enterprise" }, -// other: { locale: "en-US", feature: "beta" } -// } -``` - -The returned context object contains: - -- `user`: Current user attributes (if any) -- `company`: Current company attributes (if any) -- `other`: Additional context attributes not related to user or company - -## Toolbar - -The Reflag Toolbar is great for toggling flags on/off for yourself to ensure that everything works both when a flag is on and when it's off. - -Toolbar screenshot - -The toolbar will automatically appear on `localhost`. However, it can also be incredibly useful in production. -You have full control over when it appears through the `toolbar` configuration option passed to the `ReflagClient`. - -You can pass a simple boolean to force the toolbar to appear/disappear: - -```typescript -const client = new ReflagClient({ - // show the toolbar even in production if the user is an internal/admin user - toolbar: user?.isInternal, - ... -}); +// On the server +const bootstrappedState = serverClient.getFlagsForBootstrap(context); ``` -You can also configure the position of the toolbar on the screen: - -```typescript -const client = new ReflagClient({ - toolbar: { - show: true; - position: { - placement: "bottom-left", - offset: {x: "1rem", y: "1rem"} - } - } - ... -}) +```ts +// In the browser +const reflag = new ReflagClient({ publishableKey, bootstrappedState }); +await reflag.initialize(); ``` -See [the reference](https://docs.reflag.com/supported-languages/browser-sdk/globals#toolbaroptions) for details. - -## Qualitative feedback on beta flags - -Reflag can collect qualitative feedback from your users in the form of a [Customer Satisfaction Score](https://en.wikipedia.org/wiki/Customer_satisfaction) and a comment. - -### Automated feedback collection - -The Reflag Browser SDK comes with automated feedback collection mode enabled by default, which lets the Reflag service ask your users for feedback for relevant flags just after they've used them. - -> [!NOTE] -> To get started with automatic feedback collection, make sure you've set `user` in the `ReflagClient` constructor. - -Automated feedback surveys work even if you're not using the SDK to send events to Reflag. -It works because the Reflag Browser SDK maintains a live connection to Reflag's servers and can automatically show a feedback prompt whenever the Reflag servers determines that an event should trigger a prompt - regardless of how this event is sent to Reflag. - -You can find all the options to make changes to the default behavior in the [Reflag feedback documentation](./FEEDBACK.md). - -### Reflag feedback UI +Use Node SDK v2 and pass the whole object returned by `getFlagsForBootstrap()`, including `protocolVersion: 2`, serialized with your framework's usual mechanism. V1 bootstrap data and the old `bootstrappedFlags` option are not supported. Live updates require `flagStateVersion` in the bootstrap data. Leave secrets and server-only attributes out of the context you bootstrap, because the browser can read it. -Reflag can assist you with collecting your user's feedback by offering a pre-built UI, allowing you to get started with minimal code and effort. +Later refreshes evaluate flags using the browser's context. If values that depend on server-only attributes must not change, leave `enableLiveFlagUpdates` off (the default). -[Read the Reflag feedback UI documentation](./FEEDBACK.md) - -### Reflag feedback SDK - -Feedback can be submitted to Reflag using the SDK: +## Let users opt in to flags ```ts -reflagClient.feedback({ - flagKey: "my-flag-key", // String (required), copy from Flag feedback tab - score: 5, // Number: 1-5 (optional) - comment: "Absolutely stellar work!", // String (optional) -}); +const optInFlags = reflag.getOptInFlags(); +try { + const response = await reflag.setOptIn("huddles", { optedIn: true }); + if (!response?.ok) console.error("Could not update opt-in"); +} catch (error) { + console.error("Could not update opt-in", error); +} ``` -### Reflag feedback API +Each entry includes the flag's `key`, `name`, `description` and whether the user or company has opted in. User and company opt-ins are independent; pass `scope: "company"` to change the company's opt-in. Use `getIsLoadingOptInFlags()` and the `optInFlagsLoadingUpdated` event to show a loading state. -If you are not using the Reflag Browser SDK, you can still submit feedback using the HTTP API. +Opt-in metadata arrives with flag values and is cached with them. Bootstrapped clients fetch missing metadata on demand without replacing server-evaluated values. This request can happen even with live updates disabled. Loading settles on success or failure; failed metadata requests do not expose an error, so call `reflag.refresh()` to retry. -See details in [Feedback HTTP API](https://docs.reflag.com/api/http-api#post-feedback) +Check the mutation's returned `Response.ok` and catch rejections. HTTP failures return a readable non-OK response without refreshing; skipped calls return `undefined`. Successful mutations wait for updated values and membership confirmation, but confirmation can fail after membership has changed remotely. -## Tracking flag usage +## Overrides and toolbar -The `track` function lets you send events to Reflag to denote flag usage. -By default Reflag expects event names to align with the flag keys, but -you can customize it as you wish. +Override flags locally while developing or testing: ```ts -reflagClient.track("huddle", { voiceHuddle: true }); +reflag.setFlagOverride("huddles", true); +reflag.setFlagOverride("assistant-settings", { model: "local" }); +reflag.setFlagOverride("huddles", undefined); // remove the override ``` -## Event listeners - -Event listeners allow for capturing various events occurring in the `ReflagClient`. This is useful to build integrations with other system or for various debugging purposes. The available events are: - -- `check`: Your code used `isEnabled` or `config` for a flag -- `flagsUpdated`: Flags were updated. Either because they were loaded as part of initialization or because the user/company updated -- `optInFlagsLoadingUpdated`: The opt-in flag loading state changed -- `user`: User information updated (similar to the `identify` call used in tracking terminology) -- `company`: Company information updated (sometimes to the `group` call used in tracking terminology) -- `track`: Track event occurred. - -Use the `on()` method to add an event listener to respond to certain events. See the API reference for details on each hook. +The toolbar shows on `localhost` by default and lets you toggle Boolean flags for yourself. Use the `toolbar` option to show it elsewhere, for example to internal users in production: ```ts -import { ReflagClient, CheckEvent, RawFlags } from "@reflag/browser-sdk"; - -const client = new ReflagClient({ - // options +const reflag = new ReflagClient({ + publishableKey, + toolbar: user.isInternal, // show the toolbar to internal users }); - -// or add the hooks after construction: -const unsub = client.on("check", (check: CheckEvent) => - console.log(`Check event ${check}`), -); -// use the returned function to unsubscribe, or call `off()` with the same arguments again -unsub(); -``` - -## Zero PII - -The Reflag Browser SDK doesn't collect any metadata and HTTP IP addresses are _not_ being stored. - -For tracking individual users, we recommend using something like database ID as userId, as it's unique and doesn't include any PII (personal identifiable information). If, however, you're using e.g. email address as userId, but prefer not to send any PII to Reflag, you can hash the sensitive data before sending it to Reflag: - -```ts -import reflag from "@reflag/browser-sdk"; -import { sha256 } from "crypto-hash"; - -reflag.user(await sha256("john_doe")); ``` -## Use of cookies +## Events -The Reflag Browser SDK uses a couple of cookies to support automated feedback surveys. These cookies are not used for tracking purposes and thus should not need to appear in cookie consent forms. +`on(event, handler)` subscribes to client events and returns an unsubscribe function. Events include `stateUpdated`, `flagsUpdated`, `check`, `track`, `user`, `company` and `optInFlagsLoadingUpdated`. -The two cookies are: +## Configuration -- `reflag-prompt-${userId}`: store the last automated feedback prompt message ID received to avoid repeating surveys -- `reflag-token-${userId}`: caching a token used to connect to Reflag's live messaging infrastructure that is used to deliver automated feedback surveys in real time. +| Option | Description | +| -------------------------- | --------------------------------------------------------------- | +| `fallbackFlags` | Values to use if flags can't be fetched | +| `enableLiveFlagUpdates` | Update flags when they change in Reflag; default `false` | +| `staleTimeMs` | How long cached flags count as fresh; default `0` | +| `staleWhileRevalidate` | Use stale cached flags while fetching new ones; default `false` | +| `expireTimeMs` | How long cached flags are kept; default 30 days | +| `timeoutMs` | Flag request timeout; default 5,000 ms | +| `enableTracking` | Set to `false` to stop sending checks and usage events | +| `offline` | Make no network requests, for example in tests | +| `toolbar`, `feedback` | Toolbar and feedback UI options | +| `logger` | Custom logger | +| `apiBaseUrl`, `appBaseUrl` | Override the API and app URLs | +| `credentials` | Fetch credentials mode | +| `storage` | Custom async storage for the flag cache | +| `eventSourceFactory` | Custom EventSource implementation for runtimes without one | +| `trackingQueue` | Event batching: `flushDelayMs` and `maxSize` | -## TypeScript +## Shut down -Types are bundled together with the library and exposed automatically when importing through a package manager. +Call `await reflag.stop()` to send buffered events and close the client, for example when the user signs out. ## Content Security Policy (CSP) -If you are running with strict Content Security Policies active on your website, you will need to enable these directives in order to use the SDK: - -| Directive | Values | Reason | -| ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| connect-src | [https://front.reflag.com](https://front.reflag.com) | API requests plus Server-Sent Events for live flag updates and automated feedback surveys. | -| style-src | 'unsafe-inline' | The feedback UI is styled with inline styles. Not having this directive results unstyled HTML elements. | - -If you are including the Reflag tracking SDK with a ` - - - - +```sh +npm install @reflag/vue-sdk ``` -If using Nuxt, wrap `` in ``. `` only renders client-side currently. - -### 2. Use `useFlag get flag status +Wrap your application in `ReflagProvider` with your **publishable** key and the signed-in user's context: ```vue - -``` - -See [useFlag()](#useflag) for a full example - -## Setting context - -Reflag determines which flags are active for a given `user`, `company`, or `other` context. -You can pass these to the `ReflagProvider` using the `context` prop. - -### Using the `context` prop - -```vue - - - -``` - -### Legacy individual props (deprecated) - -For backward compatibility, you can still use individual props, but these are deprecated and will be removed in the next major version: - -```vue - - - -``` - -> [!Important] -> The `user`, `company`, and `otherContext` props are deprecated. Use the `context` prop instead, which provides the same functionality in a more structured way. - -### Context requirements - -If you supply `user` or `company` objects, they must include at least the `id` property otherwise they will be ignored in their entirety. -In addition to the `id`, you must also supply anything additional that you want to be able to evaluate flag targeting rules against. -Attributes which are not properties of the `user` or `company` can be supplied using the `other` property. - -Attributes cannot be nested (multiple levels) and must be either strings, numbers or booleans. -A number of special attributes exist: - -- `name` -- display name for `user`/`company`, -- `email` -- the email of the user, -- `avatar` -- the URL for `user`/`company` avatar image. - -To retrieve flags along with their targeting information, use `useFlag(key: string)` hook (described in a section below). - -Note that accessing `isEnabled` on the object returned by `useFlag()` automatically -generates a `check` event. - -## Remote config - -Remote config is a dynamic and flexible approach to configuring flag behavior outside of your app – without needing to re-deploy it. - -Similar to `isEnabled`, each flag accessed using the `useFlag()` hook, has a `config` property. This configuration is managed from within Reflag. It is managed similar to the way access to flags is managed, but instead of the -binary `isEnabled` you can have multiple configuration values which are given to different user/companies. - -### Get started with Remote config - -```ts -const { - isEnabled, - config: { key, payload }, -} = useFlag("huddles"); - -// isEnabled: true, -// key: "gpt-3.5", -// payload: { maxTokens: 10000, model: "gpt-3.5-beta1" } -``` - -`key` is mandatory for a config, but if a flag has no config or no config value was matched against the context, the `key` will be `undefined`. Make sure to check against this case when trying to use the configuration in your application. `payload` is an optional JSON value for arbitrary configuration needs. - -Note that, similar to `isEnabled`, accessing `config` on the object returned by `useFlag()` automatically -generates a `check` event. - -## `` component - -The `` initializes the Reflag SDK, fetches flags and starts listening for automated feedback survey events. The component can be configured using a number of props: - -- `publishableKey` is used to connect the provider to an _environment_ on Reflag. Find your `publishableKey` under [environment settings](https://app.reflag.com/env-current/settings/app-environments) in Reflag, -- `context`: An object containing `user`, `company`, and `other` properties that make up the evaluation context used to determine if a flag is enabled or not. `company` and `user` contexts are automatically transmitted to Reflag servers so the Reflag app can show you which companies have access to which flags etc. -- `company`, `user` and `otherContext` (deprecated): Individual props for context. These are deprecated in favor of the `context` prop and will be removed in the next major version. - - > [!Note] - > If you specify `company` and/or `user` they must have at least the `id` property, otherwise they will be ignored in their entirety. You should also supply anything additional you want to be able to evaluate flag targeting against, - -- `timeoutMs`: Timeout in milliseconds when fetching flags from the server, -- `staleWhileRevalidate`: If set to `true`, stale flags will be returned while refetching flags in the background, -- `expireTimeMs`: If set, flags will be cached between page loads for this duration (in milliseconds), -- `staleTimeMs`: Maximum time (in milliseconds) that stale flags will be returned if `staleWhileRevalidate` is true and new flags cannot be fetched. - -- `enableTracking`: Set to `false` to stop sending tracking events and user/company updates to Reflag. Useful when you're impersonating a user (defaults to `true`), -- `apiBaseUrl`: Optional base URL for the Reflag API. This also controls the SSE origin used for live flag updates and automated feedback, -- `credentials`: Optional fetch credentials mode. Set to `"include"` when proxying through your backend and authenticating with cookies; this also enables credentials for live-update SSE connections. -- `appBaseUrl`: Optional base URL for the Reflag application. Use this to override the default app URL, - -- `debug`: Set to `true` to enable debug logging to the console. If both `logger` and `debug` are provided, `logger` takes precedence, -- `logger`: Optional custom logger implementation (`debug`, `info`, `warn`, `error`) used by the underlying client, -- `toolbar`: Optional [configuration](https://docs.reflag.com/supported-languages/browser-sdk/globals#toolbaroptions) for the Reflag toolbar, -- `feedback`: Optional configuration for feedback collection - -### Loading states - -ReflagProvider lets you define a template to be shown while ReflagProvider is initializing: - -```vue ``` -If you want more control over loading screens, `useIsLoading()` returns a `Ref` which you can use to customize the loading experience. - -## `` component - -The `` component is a specialized version of `ReflagProvider` designed for server-side rendering and preloaded flag scenarios. It uses pre-fetched flags for the initial render, resulting in faster initial page loads and better SSR compatibility. - -### Usage - -```vue - - - -``` - -### Getting bootstrapped flags - -You'll typically generate the `bootstrappedFlags` object on your server using the Node.js SDK or by fetching from the Reflag API. Pass the full object returned by `getFlagsForBootstrap()` directly to ``. It contains: - -- `context`: the evaluation context used on the server -- `flags`: the evaluated raw flags -- `flagStateVersion`: an optional version used to avoid redundant live-update refreshes immediately after bootstrapping - -If you want live flag updates to continue working after bootstrapping, use a recent `@reflag/node-sdk` so `getFlagsForBootstrap()` includes `flagStateVersion`. - -With `ReflagBootstrappedProvider`, `useOptInFlags()` requests a flags refresh on first use. It reports `isLoading: true` until that refresh settles. - -Here's an example using the Node.js SDK: - -```js -// server.js (Node.js/SSR) -import { ReflagClient } from "@reflag/node-sdk"; - -const client = new ReflagClient({ - secretKey: "your-secret-key", // Use secret key on server -}); -await client.initialize(); - -// Fetch flags for specific context -const context = { - user: { id: "user123", name: "John Doe", email: "john@acme.com" }, - company: { id: "company456", name: "Acme Inc", plan: "enterprise" }, -}; - -const bootstrappedFlags = client.getFlagsForBootstrap(context); - -// Pass to your Vue app -``` - -### ReflagBootstrappedProvider Props +In Nuxt, wrap the provider in ``. -`ReflagBootstrappedProvider` accepts all the same props as `ReflagProvider` except: +### 2. Create a flag -- `flags`: The pre-fetched bootstrapped state object containing `context`, evaluated `flags`, and an optional `flagStateVersion` -- All other props available in `ReflagProvider` are supported except `context`, `user`, `company`, and `otherContext` (which are extracted from `flags.context`) +Create a flag with the key `huddles` in the Reflag app. -If the `flags` prop is not provided or is undefined, the provider will not initialize the client and will render in a non-loading state. +### 3. Read the flag -> [!NOTE] -> After bootstrapping, any live flag updates are fetched directly by the browser SDK from Reflag using the browser-visible context. If your bootstrapped snapshot depends on server-only or secret context that is not available in the browser, later live refreshes may differ. In that case, keep `enableLiveFlagUpdates` disabled. -> -> Requesting opt-in flags also triggers a browser-side refresh, even when `enableLiveFlagUpdates` is disabled. - -## `` component - -The `` is a lower-level component that accepts a pre-initialized `ReflagClient` instance. This is useful for advanced use cases where you need full control over client initialization or want to share a client instance across multiple parts of your application. - -### ReflagClientProvider Usage +Use `useFlag()` in any component: ```vue ``` -### ReflagClientProvider Props +## Read flags -The `ReflagClientProvider` accepts the following props: +`useFlag()` returns a ref that updates when the flag changes. Vue unwraps refs in templates; use `.value` in script. -- `client`: A pre-initialized `ReflagClient` instance - -### Slots - -- `loading`: Optional slot to show while the client is initializing (same as `ReflagProvider`) - -> [!Note] -> Most applications should use `ReflagProvider` or `ReflagBootstrappedProvider` instead of `ReflagClientProvider`. Only use this component when you need the advanced control it provides. - -## Hooks - -### `useFlag()` - -Returns the state of a given flag for the current context. The composable provides access to flags and their configurations. - -`useFlag()` returns an object with this shape: +Pass a flag key to check whether the flag is enabled: ```ts -{ - isEnabled: boolean, // is the flag enabled - track: () => void, // send a track event when the flag is used - requestFeedback: (...) => void // open up a feedback dialog - config: {key: string, payload: any}, // remote configuration for this flag - isLoading: boolean // if you want to manage loading state at the flag level -} -``` - -Example: - -```vue - - - +const enabled = useFlag("huddles"); // ref of true or false ``` -See the reference docs for details. - -### `useOptInFlags()` and `useSetOptIn()` - -Use these composables to build an end-user opt-in UI for flags where opt-in is enabled in Reflag. - -```vue - +To read a configuration value, pass a default as the second argument. The ref holds a value of the same type as the default: - +```ts +const model = useFlag("model", "quick"); // ref of string +const settings = useFlag("huddle-settings", { maxParticipants: 10 }); // ref of { maxParticipants: number } ``` -By default, `useSetOptIn()` changes the opt-in for the current user, so the current context must include a `user.id`. To manage the current company's opt-in instead, pass `scope: "company"`; the context must then include a `company.id`. - -User and company opt-ins are managed independently. Setting `optedIn` to `false` removes the opt-in only for the selected scope. For example, cancelling a user's opt-in does not change the company's opt-in for the same flag. - -`setOptIn` returns a promise so you can wait for the new membership state to be synchronized. On success, it resolves after the refreshed flag state has been applied locally, the requested membership change has been confirmed, and subscribers have been notified when flags change. Vue may not have committed the resulting render yet. - -The promise resolves to a `Response`, or `undefined` if skipped due to invalid input, offline mode etc. Check `response?.ok` for success. +While flags are loading, if the flag doesn't exist, or if its value has a different type, the ref holds `false`, or your default if you passed one. Pass `null` as the default to accept any JSON value and narrow it yourself. -`useOptInFlags()` returns `{ flags, isLoading }`, where both values are computed refs. With `ReflagBootstrappedProvider`, it fetches opt-in metadata on first use and reports `isLoading: true` until that refresh succeeds or fails. +The SDK checks only the top-level type of a value. If your application depends on nested fields, validate them. -If fetching opt-in metadata fails, loading ends without exposing an error. Call `client.refresh()` on the client returned by `useClient()` to retry. +Each read records a check, which Reflag uses for launch monitoring. -With a regular `ReflagProvider`, opt-in metadata arrives as part of the normal initial flags request, so `useOptInFlags().isLoading` remains `false`. Use the general `useIsLoading()` composable or the provider's loading slot for that initial loading state. +## Loading states -### `useTrack()` +`useIsLoading()` returns a Boolean ref that is `true` while the provider loads flags. You can also put loading content in the provider's `#loading` slot, as in the example above. -`useTrack()` returns a function which lets you send custom events to Reflag. It takes a string argument with the event name and optionally an object with properties to attach the event. - -Using `track` returned from `useFlag()` calls this track function with the flag key as the event name. - -```vue - - - -``` - -### `useRequestFeedback()` - -Returns a function that lets you open up a dialog to ask for feedback on a specific feature. This is useful for collecting targeted feedback about specific features. - -See [Automated Feedback Surveys](https://docs.reflag.com/product-handbook/live-satisfaction) for how to do this automatically, without code. - -When using the `useRequestFeedback` you must pass the flag key to `requestFeedback`. -The example below shows how to use `position` to ensure the popover appears next to the "Give feedback!" button. - -```vue - +requestFeedback({ flagKey: "huddles", title: "How did it go?" }); - +const sendFeedback = useSendFeedback(); +await sendFeedback({ flagKey: "huddles", score: 5 }); ``` -See the [Feedback Documentation](https://github.com/reflagcom/javascript/blob/main/packages/browser-sdk/FEEDBACK.md#manual-feedback-collection) for more information on `requestFeedback` options. +Configure your flag's adoption rules to match the event names you send. See the [Browser feedback documentation](../browser-sdk/FEEDBACK.md) to configure feedback prompts and the feedback UI. -### `useSendFeedback()` +## Update context -Returns a function that lets you send feedback to Reflag. This is useful if you've manually collected feedback through your own UI and want to send it to Reflag. +`useUpdateUser()`, `useUpdateCompany()` and `useUpdateOtherContext()` return functions that merge new attributes into the current context. To replace the whole context, call `useClient().setContext(context)`. Flag values are refetched for the new context. -```vue - - - +```ts +const flags = serverClient.getFlagsForBootstrap(context); ``` -### `useUpdateUser()`, `useUpdateCompany()` and `useUpdateOtherContext()` - -These composables return functions that let you update the attributes for the currently set user, company, or other context. Updates to user/company are stored remotely and affect flag targeting, while "other" context updates only affect the current session. +Then pass the whole result to `ReflagBootstrappedProvider`, serialized with your framework's usual mechanism: ```vue - - - + + + ``` -Note: To change the `user.id` or `company.id`, you need to update the props passed to `ReflagProvider` instead of using these composables. +Use Node SDK v2 and preserve the whole object, including `protocolVersion: 2`. V1 bootstrap data is not supported. Live updates require `flagStateVersion` in the bootstrap data. -### `useClient()` - -Returns the `ReflagClient` used by the `ReflagProvider`. The client offers more functionality that -is not directly accessible through the other composables. - -```vue - +```ts +const { flags, isLoading } = useOptInFlags(); +const setOptIn = useSetOptIn(); - +try { + const response = await setOptIn("huddles", { optedIn: true }); + if (!response?.ok) console.error("Could not update opt-in"); +} catch (error) { + console.error("Could not update opt-in", error); +} ``` -### `useIsLoading()` +Each entry includes the flag's `key`, `name`, `description` and whether the user or company has opted in. User and company opt-ins are independent; pass `scope: "company"` to change the company's opt-in. Check `isLoading` before rendering an empty state. -Returns a `Ref` to indicate if Reflag has finished loading. -Initially, the value will be `true` if no bootstrap flags have been provided and the client has not be initialized. +Opt-in metadata arrives with flag values. Bootstrapped providers fetch missing metadata on demand without replacing server-evaluated values, even with live updates disabled. `isLoading` covers initialization and metadata retrieval and settles on success or failure. Failed metadata requests do not expose an error; use `useClient().refresh()` to retry. -```vue - - - -``` +Check the mutation's returned `Response.ok` and catch rejections. HTTP failures return a readable non-OK response without refreshing; skipped calls return `undefined`. Successful mutations wait for updated values and membership confirmation, but confirmation can fail after membership has changed remotely. -### `useOnEvent()` +## Overrides and toolbar -Vue composable for listening to Reflag client events. This composable automatically handles mounting and unmounting of event listeners. - -Available events include: - -- `flagsUpdated`: Triggered when flags are updated -- `track`: Triggered when tracking events are sent -- `feedback`: Triggered when feedback is sent +The toolbar shows on `localhost` by default and lets you toggle Boolean flags for yourself. Use the `toolbar` prop to show it elsewhere, for example to internal users in production: ```vue - - - + + + ``` -You can also provide a specific client instance if needed: +To override a flag from code, call `useClient().setFlagOverride(key, value)`. Pass `undefined` to remove the override. -```vue - - - -``` +`useClient()` returns the underlying Browser SDK client. If you already create a Browser SDK client yourself, pass it to `ReflagClientProvider`; your application is then responsible for initializing and stopping it. -## Content Security Policy (CSP) +## Events -See [CSP](https://github.com/reflagcom/javascript/blob/main/packages/browser-sdk/README.md#content-security-policy-csp) for info on using Reflag React SDK with CSP +`useOnEvent(type, handler)` subscribes to [client events](../browser-sdk/README.md) and unsubscribes when the component unmounts. -## License +## Configuration -MIT License +The provider accepts the Browser SDK's configuration options, such as `fallbackFlags`, `enableTracking`, `offline`, `feedback` and `logger`, as props. Live updates are on by default in Vue; set `:enable-live-flag-updates="false"` to turn them off. Set `debug` to log to the console. -Copyright (c) 2025 Bucket ApS +For Content Security Policy requirements and the full list of options, see the [Browser SDK](../browser-sdk/README.md). diff --git a/packages/vue-sdk/dev/plain/App.vue b/packages/vue-sdk/dev/plain/App.vue index 77aa4e19b..1c799cc35 100644 --- a/packages/vue-sdk/dev/plain/App.vue +++ b/packages/vue-sdk/dev/plain/App.vue @@ -42,11 +42,14 @@ const isBootstrapped = computed(() => { v-else-if="isBootstrapped" :publishable-key="publishableKey" :flags="{ + protocolVersion: 2, context, flags: { huddles: { - key: 'huddles', - isEnabled: true, + value: true, + resolved: false, + ruleResults: [], + errors: [], }, }, }" diff --git a/packages/vue-sdk/dev/plain/components/FlagsList.vue b/packages/vue-sdk/dev/plain/components/FlagsList.vue index 6912ac6fe..0d6c770f2 100644 --- a/packages/vue-sdk/dev/plain/components/FlagsList.vue +++ b/packages/vue-sdk/dev/plain/components/FlagsList.vue @@ -1,117 +1,40 @@ - - + + diff --git a/packages/vue-sdk/dev/plain/components/StartHuddlesButton.vue b/packages/vue-sdk/dev/plain/components/StartHuddlesButton.vue index e26860c0e..350959836 100644 --- a/packages/vue-sdk/dev/plain/components/StartHuddlesButton.vue +++ b/packages/vue-sdk/dev/plain/components/StartHuddlesButton.vue @@ -1,35 +1,33 @@ + diff --git a/packages/vue-sdk/package.json b/packages/vue-sdk/package.json index e394100f5..13149aba6 100644 --- a/packages/vue-sdk/package.json +++ b/packages/vue-sdk/package.json @@ -1,6 +1,6 @@ { "name": "@reflag/vue-sdk", - "version": "1.5.7", + "version": "2.0.0-next.0", "license": "MIT", "repository": { "type": "git", @@ -25,7 +25,7 @@ "dev": "vite", "build": "tsc --project tsconfig.build.json && vite build", "test": "yarn test:types && vitest run", - "test:types": "tsc --project tsconfig.type-tests.json", + "test:types": "tsc --project tsconfig.type-tests.json && tsc --project tsconfig.type-tests-defaults.json && tsc --project tsconfig.type-tests-registered.json", "test:watch": "vitest", "test:ci": "yarn test --reporter=default --reporter=junit --outputFile=junit.xml", "coverage": "yarn test --coverage", @@ -38,7 +38,7 @@ "fmt:fix": "oxfmt --write ." }, "dependencies": { - "@reflag/browser-sdk": "1.7.4" + "@reflag/browser-sdk": "workspace:^" }, "devDependencies": { "@reflag/tsconfig": "^0.0.2", diff --git a/packages/vue-sdk/src/ReflagBootstrappedProvider.vue b/packages/vue-sdk/src/ReflagBootstrappedProvider.vue index 63216a4fb..af2169204 100644 --- a/packages/vue-sdk/src/ReflagBootstrappedProvider.vue +++ b/packages/vue-sdk/src/ReflagBootstrappedProvider.vue @@ -23,13 +23,14 @@ const client = useReflagClient({ logger, }); -const isLoading = ref( - client.getState() !== "initialized" ? initialLoading : false, -); +let hasInitialized = client.getState() === "initialized"; +const isLoading = ref(hasInitialized ? false : initialLoading); useOnEvent( "stateUpdated", (state) => { - isLoading.value = state === "initializing"; + if (state === "initialized") hasInitialized = true; + isLoading.value = + state === "initializing" && (hasInitialized || initialLoading); }, client, ); diff --git a/packages/vue-sdk/src/hooks.ts b/packages/vue-sdk/src/hooks.ts index 93eb047eb..8fcc75cff 100644 --- a/packages/vue-sdk/src/hooks.ts +++ b/packages/vue-sdk/src/hooks.ts @@ -5,6 +5,8 @@ import { onMounted, onUnmounted, ref, + shallowRef, + type ShallowRef, } from "vue"; import { @@ -20,8 +22,11 @@ import { FlagKey, OptInFlag, ProviderContextType, - RequestFlagFeedbackOptions, - TypedFlags, + Flags, + FlagDefaultFor, + FlagDefaultValue, + FlagValue, + FlagValueFromDefault, UseOptInFlagsResult, } from "./types"; import { SDK_VERSION } from "./version"; @@ -67,60 +72,32 @@ export function useReflagClient( return reflagClients.get(publishableKey)!; } -/** - * Vue composable for getting the state of a given flag for the current context. - * - * This composable returns an object with the state of the flag for the current context. - * - * @param key - The key of the flag to get the state of. - * @returns An object with the state of the flag. - * - * @example - * ```ts - * import { useFlag } from '@reflag/vue-sdk'; - * - * const { isEnabled, config, track, requestFeedback } = useFlag("huddles"); - * - * function StartHuddlesButton() { - * const { isEnabled, config: { payload }, track } = useFlag("huddles"); - * if (isEnabled) { - * return ; - * } - * ``` - */ -export function useFlag(key: TKey): TypedFlags[TKey] { +/** Reactive direct values: Boolean/false by default, or infer a positional JSON default. */ +export function useFlag( + key: FlagKey, + defaultValue?: undefined, +): ShallowRef; +export function useFlag< + Key extends FlagKey, + Default extends FlagDefaultFor, +>(key: Key, defaultValue: Default): ShallowRef>; +export function useFlag( + key: keyof Flags extends never ? string : never, + defaultValue: Default, +): ShallowRef>; +export function useFlag( + key: FlagKey, + defaultValue: FlagDefaultValue = false, +): ShallowRef { const client = useClient(); - const isLoading = useIsLoading(); - - const track = () => client.track(key); - const requestFeedback = (opts: RequestFlagFeedbackOptions) => - client.requestFeedback({ ...opts, flagKey: key }); - - const flag = ref( - client.getFlag(key) || { - isEnabled: false, - config: { key: undefined, payload: undefined }, - }, - ); - + const flag = shallowRef(client.getFlag(key, defaultValue)); const updateFlag = () => { - flag.value = client.getFlag(key); + flag.value = client.getFlag(key, defaultValue); }; - - onMounted(() => { - updateFlag(); - }); - - useOnEvent("flagsUpdated", updateFlag); - - return { - key, - isLoading, - isEnabled: computed(() => flag.value.isEnabled), - config: computed(() => flag.value.config), - track, - requestFeedback, - } as TypedFlags[TKey]; + useOnEvent("flagsUpdated", updateFlag, client); + // Catch updates between setup and listener registration. + onMounted(updateFlag); + return flag; } /** @@ -136,15 +113,15 @@ export function useFlag(key: TKey): TypedFlags[TKey] { */ export function useOptInFlags(): UseOptInFlagsResult { const client = useClient(); - const isBootstrapped = client.getConfig().bootstrapped; + const isLoading = useIsLoading(); const optInFlags = ref(client.getOptInFlags() as OptInFlag[]); const isOptInFlagsLoading = ref(client.getIsLoadingOptInFlags()); const updateOptInFlags = () => { optInFlags.value = client.getOptInFlags() as OptInFlag[]; }; - const updateIsLoading = (isLoading = client.getIsLoadingOptInFlags()) => { - isOptInFlagsLoading.value = isLoading; + const updateIsLoading = (loading = client.getIsLoadingOptInFlags()) => { + isOptInFlagsLoading.value = loading; }; useOnEvent("flagsUpdated", updateOptInFlags, client); @@ -157,7 +134,7 @@ export function useOptInFlags(): UseOptInFlagsResult { return { flags: computed(() => optInFlags.value), - isLoading: computed(() => isBootstrapped && isOptInFlagsLoading.value), + isLoading: computed(() => isLoading.value || isOptInFlagsLoading.value), }; } diff --git a/packages/vue-sdk/src/index.ts b/packages/vue-sdk/src/index.ts index 85b10c946..1cfa56847 100644 --- a/packages/vue-sdk/src/index.ts +++ b/packages/vue-sdk/src/index.ts @@ -20,11 +20,11 @@ export { } from "./hooks"; export type { BootstrappedFlags, - EmptyFlagRemoteConfig, - Flag, + FlagValue, + FlagDefaultValue, + FlagValueFromDefault, FlagKey, Flags, - FlagType, OptInFlag, ReflagBaseProps, ReflagBootstrappedProps, diff --git a/packages/vue-sdk/src/types.ts b/packages/vue-sdk/src/types.ts index 3ec8794d2..ade540ff1 100644 --- a/packages/vue-sdk/src/types.ts +++ b/packages/vue-sdk/src/types.ts @@ -6,51 +6,31 @@ import type { InitOptions, Logger, OptInFlag as BrowserOptInFlag, - RawFlags, + FlagValue, + FlagDefaultFor, + FlagDefaultValue, + FlagValueFromDefault, ReflagClient, ReflagContext, RequestFeedbackData, UserContext, } from "@reflag/browser-sdk"; -export type EmptyFlagRemoteConfig = { key: undefined; payload: undefined }; - -export type FlagType = { - config?: { - payload: any; - }; +export type { + FlagValue, + FlagDefaultFor, + FlagDefaultValue, + FlagValueFromDefault, }; -export type FlagRemoteConfig = - | { - key: string; - payload: any; - } - | EmptyFlagRemoteConfig; - -export interface Flag< - TConfig extends FlagType["config"] = EmptyFlagRemoteConfig, -> { - key: string; - isEnabled: Ref; - isLoading: Ref; - config: Ref<({ key: string } & TConfig) | EmptyFlagRemoteConfig>; - track(): Promise | undefined; - requestFeedback: (opts: RequestFlagFeedbackOptions) => void; -} - // eslint-disable-next-line @typescript-eslint/no-empty-object-type export interface Flags {} - export type TypedFlags = keyof Flags extends never - ? Record - : { - [TypedFlagKey in keyof Flags]: Flags[TypedFlagKey] extends FlagType - ? Flag - : Flag; - }; - -export type FlagKey = keyof TypedFlags; + ? Record + : { [Key in keyof Flags]: Flags[Key] | undefined }; +export type FlagKey = keyof Flags extends never + ? string + : Extract; /** * An opt-in-enabled flag for the generated Vue SDK flag definitions. @@ -73,9 +53,7 @@ export interface ProviderContextType { isLoading: Ref; } -export type BootstrappedFlags = BrowserBootstrappedState & { - flags: RawFlags; -}; +export type BootstrappedFlags = BrowserBootstrappedState; export type RequestFlagFeedbackOptions = Omit< RequestFeedbackData, diff --git a/packages/vue-sdk/test/opt-in-types.ts b/packages/vue-sdk/test/opt-in-types.ts index a5c0e05f1..690b95e02 100644 --- a/packages/vue-sdk/test/opt-in-types.ts +++ b/packages/vue-sdk/test/opt-in-types.ts @@ -1,8 +1,9 @@ -import { useOptInFlags, useSetOptIn } from "@reflag/vue-sdk"; +import { useFlag, useOptInFlags, useSetOptIn } from "@reflag/vue-sdk"; declare module "@reflag/vue-sdk" { interface Flags { - "generated-opt-in-flag": {}; + "generated-opt-in-flag": boolean; + legacy: { isEnabled: boolean; config: { payload: string } }; } } @@ -19,5 +20,10 @@ export function GeneratedOptInTypes() { // @ts-expect-error generated flag types still reject unknown literal keys void setOptIn("unknown-flag", { optedIn: true }); - return loading; + const enabled: boolean = useFlag("generated-opt-in-flag").value; + // @ts-expect-error old registered wrappers cannot change the Boolean contract + void useFlag("legacy").value.isEnabled; + // @ts-expect-error registration still constrains singular keys + useFlag("unknown-flag"); + return loading || enabled; } diff --git a/packages/vue-sdk/test/usage.test.ts b/packages/vue-sdk/test/usage.test.ts index 66cf0c19c..5e14dd063 100644 --- a/packages/vue-sdk/test/usage.test.ts +++ b/packages/vue-sdk/test/usage.test.ts @@ -18,14 +18,8 @@ import { beforeAll(() => { vi.spyOn(ReflagClient.prototype, "initialize").mockResolvedValue(undefined); vi.spyOn(ReflagClient.prototype, "stop").mockResolvedValue(undefined); - vi.spyOn(ReflagClient.prototype, "getFlag").mockReturnValue({ - isEnabled: true, - config: { key: "default", payload: { message: "Hello" } }, - track: vi.fn().mockResolvedValue(undefined), - requestFeedback: vi.fn(), - setIsEnabledOverride: vi.fn(), - isEnabledOverride: null, - }); + vi.spyOn(ReflagClient.prototype, "getFlag").mockReturnValue(true); + vi.spyOn(ReflagClient.prototype, "getState").mockReturnValue("initialized"); vi.spyOn(ReflagClient.prototype, "getFlags").mockReturnValue({}); vi.spyOn(ReflagClient.prototype, "getOptInFlags").mockReturnValue([]); vi.spyOn(ReflagClient.prototype, "getIsLoadingOptInFlags").mockReturnValue( @@ -42,6 +36,7 @@ beforeAll(() => { beforeEach(() => { vi.clearAllMocks(); + vi.mocked(ReflagClient.prototype.getFlag).mockReturnValue(true); vi.mocked(ReflagClient.prototype.getOptInFlags).mockReturnValue([]); vi.mocked(ReflagClient.prototype.getIsLoadingOptInFlags).mockReturnValue( false, @@ -60,6 +55,64 @@ function getProvider() { } describe("ReflagProvider", () => { + test("useFlag returns a direct reactive value, forwards positional defaults and unsubscribes", async () => { + let update: (() => void) | undefined; + const unsubscribe = vi.fn(); + vi.mocked(ReflagClient.prototype.on).mockImplementation( + (event, handler) => { + if (event === "flagsUpdated") update = handler as () => void; + return unsubscribe; + }, + ); + vi.mocked(ReflagClient.prototype.getFlag) + .mockReturnValueOnce(false) + .mockReturnValue(false); + const Child = defineComponent({ + setup() { + return { enabled: useFlag("release") }; + }, + template: "{{ enabled }}", + }); + const wrapper = mount(ReflagProvider, { + props: { publishableKey: "reactive-direct-value" }, + slots: { default: () => h(Child) }, + }); + await nextTick(); + expect(wrapper.text()).toBe("false"); + expect(ReflagClient.prototype.getFlag).toHaveBeenCalledWith( + "release", + false, + ); + vi.mocked(ReflagClient.prototype.getFlag).mockReturnValue(true); + update?.(); + await nextTick(); + expect(wrapper.text()).toBe("true"); + wrapper.unmount(); + expect(unsubscribe).toHaveBeenCalled(); + }); + + test("useFlag forwards JSON defaults without wrappers or truthiness fallback", async () => { + vi.mocked(ReflagClient.prototype.getFlag).mockReturnValue(null); + const fallback = { model: "default" }; + const Child = defineComponent({ + setup() { + return { settings: useFlag("settings", fallback) }; + }, + template: "{{ settings === null ? 'off' : settings.model }}", + }); + const wrapper = mount(ReflagProvider, { + props: { publishableKey: "reactive-json-default" }, + slots: { default: () => h(Child) }, + }); + await nextTick(); + expect(ReflagClient.prototype.getFlag).toHaveBeenCalledWith( + "settings", + fallback, + ); + expect(wrapper.text()).toBe("off"); + wrapper.unmount(); + }); + test("provides the client", async () => { const Child = defineComponent({ setup() { @@ -156,7 +209,7 @@ describe("ReflagProvider", () => { await nextTick(); expect(wrapper.findComponent(Child).vm.flags).toEqual(optInFlags); - expect(wrapper.findComponent(Child).vm.isLoading).toBe(false); + expect(wrapper.findComponent(Child).vm.isLoading).toBe(true); expect(ReflagClient.prototype.on).toHaveBeenCalledWith( "flagsUpdated", expect.any(Function), @@ -195,12 +248,16 @@ describe("ReflagProvider", () => { props: { publishableKey: "key-loading-opt-in-flags", flags: { + protocolVersion: 2, context: { user: { id: "user-1" } }, flags: { optInFlag: { - key: "optInFlag", - isEnabled: false, - targetingVersion: 1, + value: false, + resolved: true, + variantKey: "false", + sourceVersionId: "version-1", + ruleResults: [], + errors: [], }, }, }, @@ -348,15 +405,19 @@ describe("ReflagProvider", () => { describe("ReflagBootstrappedProvider", () => { const bootstrappedFlags = { + protocolVersion: 2 as const, context: { user: { id: "test-user" }, company: { id: "test-company" }, }, flags: { "test-flag": { - key: "test-flag", - isEnabled: true, - config: { key: "default", payload: { message: "Hello" } }, + value: true, + resolved: true, + variantKey: "true", + sourceVersionId: "version-1", + ruleResults: [], + errors: [], }, }, flagStateVersion: 1, @@ -382,7 +443,7 @@ describe("ReflagBootstrappedProvider", () => { await nextTick(); expect(wrapper.findComponent(Child).vm.client).toBeDefined(); - expect(wrapper.findComponent(Child).vm.flag.isEnabled.value).toBe(true); + expect(wrapper.findComponent(Child).vm.flag).toBe(true); }); test("enables live flag updates by default for bootstrapped providers", async () => { diff --git a/packages/vue-sdk/tsconfig.type-tests-defaults.json b/packages/vue-sdk/tsconfig.type-tests-defaults.json new file mode 100644 index 000000000..d8f91f7fe --- /dev/null +++ b/packages/vue-sdk/tsconfig.type-tests-defaults.json @@ -0,0 +1,5 @@ +{ + "extends": "./tsconfig.type-tests.json", + "compilerOptions": { "noUnusedLocals": false, "noUnusedParameters": false }, + "include": ["src", "type-tests/defaults.ts"] +} diff --git a/packages/vue-sdk/tsconfig.type-tests-registered.json b/packages/vue-sdk/tsconfig.type-tests-registered.json new file mode 100644 index 000000000..9114cfb03 --- /dev/null +++ b/packages/vue-sdk/tsconfig.type-tests-registered.json @@ -0,0 +1,5 @@ +{ + "extends": "./tsconfig.type-tests.json", + "compilerOptions": { "noUnusedLocals": false, "noUnusedParameters": false }, + "include": ["src", "type-tests/registered-defaults.ts"] +} diff --git a/packages/vue-sdk/type-tests/defaults.ts b/packages/vue-sdk/type-tests/defaults.ts new file mode 100644 index 000000000..eed8b6cb4 --- /dev/null +++ b/packages/vue-sdk/type-tests/defaults.ts @@ -0,0 +1,31 @@ +import type { ShallowRef } from "vue"; + +import { FlagValue, useFlag } from "@reflag/vue-sdk"; + +export function DefaultContracts() { + const enabled: ShallowRef = useFlag("release"); + const settings = useFlag("settings", { + model: "quick", + limits: [1], + } as const); + settings.value.model = "quality"; + settings.value.limits.push(2); + const _model: ShallowRef = useFlag("model", "quick"); + const _arbitrary: ShallowRef = useFlag("nullable", null); + // @ts-expect-error legacy wrappers are no longer returned + const { isEnabled: _isEnabled } = useFlag("release"); + // @ts-expect-error Boolean refs do not contain legacy wrapper fields + void enabled.value.isEnabled; + interface Settings { + model: string; + limits: number[]; + } + const fallback: Settings = { model: "quick", limits: [1] }; + const _interface: ShallowRef = useFlag("settings", fallback); + const _explicit: ShallowRef = useFlag( + "settings", + fallback, + ); + // @ts-expect-error literal defaults widen + const _literal: ShallowRef<"quick"> = useFlag("model", "quick"); +} diff --git a/packages/vue-sdk/type-tests/registered-defaults.ts b/packages/vue-sdk/type-tests/registered-defaults.ts new file mode 100644 index 000000000..aee065507 --- /dev/null +++ b/packages/vue-sdk/type-tests/registered-defaults.ts @@ -0,0 +1,65 @@ +import type { ShallowRef } from "vue"; + +import { FlagValue, useFlag } from "@reflag/vue-sdk"; + +interface Prompt { + tone: string; +} +interface Settings { + model: "quick" | "quality"; + prompt: Prompt; + methods: string[]; +} + +declare module "@reflag/vue-sdk" { + interface Flags { + enabled: boolean; + settings: Settings; + days: number; + arbitrary: FlagValue; + unknownArray: FlagValue[]; + methods: string[]; + model: "quick" | "quality"; + nullable: Settings | null; + } +} + +export function RegisteredContracts() { + const fallback: Settings = { + model: "quick", + prompt: { tone: "concise" }, + methods: ["standard"], + }; + const _settings = useFlag("settings", fallback); + const _arbitraryShape = useFlag("arbitrary", fallback); + const _unknownArray = useFlag("unknownArray", [fallback]); + const mutable = useFlag("settings", { + model: "quick", + prompt: { tone: "concise" }, + methods: ["standard"], + } as const); + mutable.value.model = "quality"; + mutable.value.prompt.tone = "detailed"; + mutable.value.methods.push("express"); + const _bare: ShallowRef = useFlag("settings"); + const _model: ShallowRef = useFlag("model", "quick"); + const _array: ShallowRef = useFlag("methods", [ + "standard", + ] as const); + const _arbitrary: ShallowRef = useFlag("settings", null); + const _nullable: ShallowRef = useFlag("nullable", null); + // @ts-expect-error Registered keys reject unknown names. + useFlag("unknown", false); + // @ts-expect-error A numeric flag elsewhere in the registry must not permit this mismatch. + useFlag("settings", 123); + // @ts-expect-error Required fields must be present. + useFlag("settings", { model: "quick" }); + // @ts-expect-error Nested property types must match. + useFlag("settings", { model: "quick", prompt: { tone: 3 }, methods: [] }); + // @ts-expect-error Registered literal unions constrain defaults. + useFlag("model", "unknown"); + // @ts-expect-error Array elements must match. + useFlag("methods", [123]); + // @ts-expect-error An explicit generic must not bypass the key's registered schema. + useFlag("settings", 123); +} diff --git a/packages/vue-sdk/vite.config.mjs b/packages/vue-sdk/vite.config.mjs index 7d25d020c..47378ece9 100644 --- a/packages/vue-sdk/vite.config.mjs +++ b/packages/vue-sdk/vite.config.mjs @@ -19,7 +19,7 @@ export default defineConfig({ }, plugins: [ vue(), - dts({ insertTypesEntry: true, exclude: ["dev"] }), + dts({ insertTypesEntry: true, exclude: ["dev"], aliasesExclude: ["vue"] }), preserveDirectives(), ], build: { diff --git a/scripts/release-channel.mjs b/scripts/release-channel.mjs new file mode 100644 index 000000000..3d3ecd51e --- /dev/null +++ b/scripts/release-channel.mjs @@ -0,0 +1,26 @@ +import { existsSync, readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +export function releaseChannel(preState) { + if (preState === undefined) return "latest"; + if ( + !preState || + !["pre", "exit"].includes(preState.mode) || + preState.tag !== "next" + ) { + throw new Error("Expected Changesets prerelease state with tag next"); + } + return preState.mode === "pre" ? "next" : "latest"; +} + +if ( + process.argv[1] && + resolve(process.argv[1]) === fileURLToPath(import.meta.url) +) { + const path = new URL("../.changeset/pre.json", import.meta.url); + const preState = existsSync(path) + ? JSON.parse(readFileSync(path, "utf8")) + : undefined; + console.log(`prerelease=${releaseChannel(preState) === "next"}`); +} diff --git a/scripts/release-channel.test.mjs b/scripts/release-channel.test.mjs new file mode 100644 index 000000000..95d5fc106 --- /dev/null +++ b/scripts/release-channel.test.mjs @@ -0,0 +1,203 @@ +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { test } from "node:test"; +import { fileURLToPath } from "node:url"; + +import getReleasePlan from "@changesets/get-release-plan"; + +import { releaseChannel } from "./release-channel.mjs"; + +const root = fileURLToPath(new URL("../", import.meta.url)); +const read = (path) => readFileSync(join(root, path), "utf8"); + +test("next prereleases do not promote stable docs", () => { + assert.equal(releaseChannel({ mode: "pre", tag: "next" }), "next"); +}); + +test("stable docs resume after explicitly exiting prerelease mode", () => { + assert.equal(releaseChannel({ mode: "exit", tag: "next" }), "latest"); + assert.equal(releaseChannel(undefined), "latest"); +}); + +test("malformed or unexpected release channels fail closed", () => { + for (const state of [ + null, + {}, + { mode: "pre" }, + { mode: "pre", tag: "latest" }, + { mode: "pre", tag: "beta" }, + { mode: "invalid", tag: "next" }, + ]) { + assert.throws(() => releaseChannel(state), /prerelease state/); + } +}); + +test("the channel command produces only the GitHub Actions output", () => { + const path = join(root, ".changeset/pre.json"); + const state = existsSync(path) ? JSON.parse(readFileSync(path)) : undefined; + const output = execFileSync( + process.execPath, + [join(root, "scripts/release-channel.mjs")], + { encoding: "utf8" }, + ); + assert.equal(output, `prerelease=${releaseChannel(state) === "next"}\n`); +}); + +test("all stable-doc publication steps require a stable release channel", () => { + const workflow = read(".github/workflows/publish.yml"); + assert.match( + workflow, + /id: release-channel\s+run: node scripts\/release-channel\.mjs >> "\$GITHUB_OUTPUT"/, + ); + const conditions = workflow + .split("\n") + .map((line) => line.trim()) + .filter((line) => line.startsWith("if: ")); + assert.equal(conditions.length, 4); + for (const condition of conditions) { + assert.equal( + condition, + "if: steps.changesets.outputs.published == 'true' && steps.release-channel.outputs.prerelease == 'false'", + ); + } + assert.match(workflow, /version: yarn version-packages/); + assert.match(workflow, /publish: yarn release-packages/); + assert.match( + read(".github/workflows/package-ci.yml"), + /run: yarn test:release/, + ); +}); + +test("the real Changesets release plan follows the selected channel", async () => { + // Use the planner directly: `changeset status` also checks git changes, which + // can reject a correctly versioned release PR with no unconsumed changesets. + const plan = await getReleasePlan(root); + const path = join(root, ".changeset/pre.json"); + const state = existsSync(path) ? JSON.parse(readFileSync(path)) : undefined; + const channel = releaseChannel(state); + for (const release of plan.releases.filter((item) => item.type !== "none")) { + assert.match( + release.newVersion, + channel === "next" ? /^\d+\.\d+\.\d+-next\.\d+$/ : /^\d+\.\d+\.\d+$/, + `Unexpected ${channel} version for ${release.name}`, + ); + } + // The first version PR must cover the complete v2 SDK family, not Node only. + // After versioning, consumed changesets need not produce another release. + if (channel === "next" && state.changesets.length === 0) { + for (const name of [ + "@reflag/node-sdk", + "@reflag/browser-sdk", + "@reflag/react-sdk", + "@reflag/vue-sdk", + "@reflag/react-native-sdk", + ]) { + assert.ok( + plan.releases.some( + (release) => release.name === name && release.type !== "none", + ), + `Missing initial prerelease for ${name}`, + ); + } + } +}); + +for (const skipped of ["ignored", "private"]) { + test(`prerelease exit preserves ${skipped} and unversioned workspaces`, async () => { + // Backport of changesets/changesets#2092: an absent prerelease counter must + // not become a patch release of our private, unpublished @reflag/tsconfig. + const directory = mkdtempSync(join(tmpdir(), "reflag-pre-exit-")); + const writeJSON = (path, value) => { + const file = join(directory, path); + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, JSON.stringify(value)); + }; + const readJSON = (path) => + JSON.parse(readFileSync(join(directory, path), "utf8")); + try { + writeJSON("package.json", { + name: "release-fixture", + private: true, + packageManager: "yarn@4.10.3", + workspaces: ["packages/*"], + }); + writeFileSync(join(directory, "yarn.lock"), ""); + writeJSON(".changeset/config.json", { + changelog: false, + commit: false, + fixed: [], + linked: [], + access: "public", + baseBranch: "main", + updateInternalDependencies: "patch", + ignore: skipped === "ignored" ? ["@reflag/tsconfig"] : [], + privatePackages: { version: skipped !== "private", tag: false }, + }); + writeJSON("packages/sdk/package.json", { + name: "@reflag/browser-sdk", + version: "2.0.0-next.1", + devDependencies: { "@reflag/tsconfig": "0.0.2" }, + }); + writeJSON("packages/tsconfig/package.json", { + name: "@reflag/tsconfig", + version: "0.0.2", + private: true, + }); + writeJSON("packages/example/package.json", { + name: "unversioned-example", + private: true, + }); + writeJSON(".changeset/pre.json", { + mode: "exit", + tag: "next", + initialVersions: { + "@reflag/browser-sdk": "2.0.0-next.0", + "@reflag/tsconfig": "0.0.2", + }, + changesets: ["sdk-major"], + }); + writeFileSync( + join(directory, ".changeset/sdk-major.md"), + '---\n"@reflag/browser-sdk": major\n---\n\nSDK v2\n', + ); + const plan = await getReleasePlan(directory); + assert.deepEqual( + plan.releases.map(({ name, newVersion }) => ({ name, newVersion })), + [{ name: "@reflag/browser-sdk", newVersion: "2.0.0" }], + ); + execFileSync( + process.execPath, + [ + fileURLToPath(import.meta.resolve("@changesets/cli/bin.js")), + "version", + ], + { cwd: directory, stdio: "pipe" }, + ); + assert.equal(readJSON("packages/sdk/package.json").version, "2.0.0"); + assert.equal( + readJSON("packages/sdk/package.json").devDependencies[ + "@reflag/tsconfig" + ], + "0.0.2", + ); + assert.equal(readJSON("packages/tsconfig/package.json").version, "0.0.2"); + assert.equal( + readJSON("packages/example/package.json").version, + undefined, + ); + assert.equal(existsSync(join(directory, ".changeset/pre.json")), false); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }); +} diff --git a/yarn.lock b/yarn.lock index a8c831a00..56d501cd9 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1769,7 +1769,7 @@ __metadata: languageName: node linkType: hard -"@changesets/assemble-release-plan@npm:^6.0.9": +"@changesets/assemble-release-plan@npm:6.0.9": version: 6.0.9 resolution: "@changesets/assemble-release-plan@npm:6.0.9" dependencies: @@ -1783,6 +1783,20 @@ __metadata: languageName: node linkType: hard +"@changesets/assemble-release-plan@patch:@changesets/assemble-release-plan@npm%3A6.0.9#~/.yarn/patches/@changesets-assemble-release-plan-npm-6.0.9-e01af97ef4.patch": + version: 6.0.9 + resolution: "@changesets/assemble-release-plan@patch:@changesets/assemble-release-plan@npm%3A6.0.9#~/.yarn/patches/@changesets-assemble-release-plan-npm-6.0.9-e01af97ef4.patch::version=6.0.9&hash=c0de35" + dependencies: + "@changesets/errors": "npm:^0.2.0" + "@changesets/get-dependents-graph": "npm:^2.1.3" + "@changesets/should-skip-package": "npm:^0.1.2" + "@changesets/types": "npm:^6.1.0" + "@manypkg/get-packages": "npm:^1.1.3" + semver: "npm:^7.5.3" + checksum: 10c0/8898084f7128fa38d0c1fd58900e24471cd49dc950352fecb0e79ff0a80d40649f57cbd56cd2a16697feed38a3388fc85926d6e9c42e0ca98718e705a09246e8 + languageName: node + linkType: hard + "@changesets/changelog-git@npm:^0.2.1": version: 0.2.1 resolution: "@changesets/changelog-git@npm:0.2.1" @@ -6029,7 +6043,19 @@ __metadata: languageName: node linkType: hard -"@reflag/browser-sdk@npm:1.7.4, @reflag/browser-sdk@workspace:packages/browser-sdk": +"@reflag/browser-sdk@npm:1.7.4": + version: 1.7.4 + resolution: "@reflag/browser-sdk@npm:1.7.4" + dependencies: + "@floating-ui/dom": "npm:^1.6.8" + fast-equals: "npm:^5.2.2" + js-cookie: "npm:^3.0.5" + preact: "npm:^10.22.1" + checksum: 10c0/11347fc0bae8e77f9e2207b520ae3e227fb88d050ff23f94614c6b5d5886c731c17634844a653fb6827e47e074a1651a9bd5f92e1f2e5704e29f0b259589d55b + languageName: node + linkType: hard + +"@reflag/browser-sdk@workspace:^, @reflag/browser-sdk@workspace:packages/browser-sdk": version: 0.0.0-use.local resolution: "@reflag/browser-sdk@workspace:packages/browser-sdk" dependencies: @@ -6153,7 +6179,7 @@ __metadata: languageName: node linkType: hard -"@reflag/node-sdk@workspace:*, @reflag/node-sdk@workspace:packages/node-sdk": +"@reflag/node-sdk@workspace:*, @reflag/node-sdk@workspace:^, @reflag/node-sdk@workspace:packages/node-sdk": version: 0.0.0-use.local resolution: "@reflag/node-sdk@workspace:packages/node-sdk" dependencies: @@ -6220,22 +6246,27 @@ __metadata: resolution: "@reflag/react-native-sdk@workspace:packages/react-native-sdk" dependencies: "@react-native-async-storage/async-storage": "npm:^2.2.0" - "@reflag/react-sdk": "npm:1.7.4" + "@reflag/node-sdk": "workspace:*" + "@reflag/react-sdk": "workspace:^" "@reflag/tsconfig": "npm:^0.0.2" + "@types/node": "npm:^22.12.0" "@types/react": "npm:^19.0.12" + "@types/react-test-renderer": "npm:^19.0.0" react-native-sse: "npm:^1.2.1" + react-test-renderer: "npm:19.1.0" typescript: "npm:^5.7.3" + vitest: "npm:~4.1.12" peerDependencies: - react: "*" + react: ">=17.0.0" react-native: "*" languageName: unknown linkType: soft -"@reflag/react-sdk@npm:1.7.4, @reflag/react-sdk@workspace:^, @reflag/react-sdk@workspace:packages/react-sdk": +"@reflag/react-sdk@workspace:^, @reflag/react-sdk@workspace:packages/react-sdk": version: 0.0.0-use.local resolution: "@reflag/react-sdk@workspace:packages/react-sdk" dependencies: - "@reflag/browser-sdk": "npm:1.7.4" + "@reflag/browser-sdk": "workspace:^" "@reflag/tsconfig": "npm:^0.0.2" "@testing-library/react": "npm:^15.0.7" "@types/jsdom": "npm:^21.1.6" @@ -6243,6 +6274,7 @@ __metadata: "@types/react": "npm:^19.0.12" "@types/react-dom": "npm:^19.0.5" "@types/webpack": "npm:^5.28.5" + fast-equals: "npm:^5.2.2" jsdom: "npm:^24.1.0" msw: "npm:^2.15.0" react: "npm:19.1.0" @@ -6284,7 +6316,7 @@ __metadata: version: 0.0.0-use.local resolution: "@reflag/vue-sdk@workspace:packages/vue-sdk" dependencies: - "@reflag/browser-sdk": "npm:1.7.4" + "@reflag/browser-sdk": "workspace:^" "@reflag/tsconfig": "npm:^0.0.2" "@types/jsdom": "npm:^21.1.6" "@types/node": "npm:^22.12.0" @@ -7425,6 +7457,15 @@ __metadata: languageName: node linkType: hard +"@types/react-test-renderer@npm:^19.0.0": + version: 19.3.1 + resolution: "@types/react-test-renderer@npm:19.3.1" + dependencies: + "@types/react": "npm:*" + checksum: 10c0/330305cd5dbefa21233a04e432d06b6d3b8ba6bad83a3e9773eba8b1731d6c9b7bdc634999d590d042e5ca7f3543e04921b963d392fbda2bbd1ba2655851dfa0 + languageName: node + linkType: hard + "@types/react@npm:*, @types/react@npm:^18": version: 18.3.3 resolution: "@types/react@npm:18.3.3" @@ -15140,7 +15181,7 @@ __metadata: version: 0.0.0-use.local resolution: "nextjs-bootstrap-demo@workspace:packages/react-sdk/dev/nextjs-bootstrap-demo" dependencies: - "@reflag/node-sdk-v1": "npm:@reflag/node-sdk@1.8.3" + "@reflag/node-sdk": "workspace:^" "@reflag/react-sdk": "workspace:^" "@types/node": "npm:^22.12.0" "@types/react": "npm:^18" @@ -17288,6 +17329,13 @@ __metadata: languageName: node linkType: hard +"react-is@npm:^19.1.0": + version: 19.3.1 + resolution: "react-is@npm:19.3.1" + checksum: 10c0/428e02d986d56f1859c57756084489f6d2900fd686905003c405b32f1168738b78772bfa4bb6c706f5ac821199171522c28bf6434281f524f901459390a19606 + languageName: node + linkType: hard + "react-native-safe-area-context@npm:^5.6.0": version: 5.6.2 resolution: "react-native-safe-area-context@npm:5.6.2" @@ -17362,6 +17410,18 @@ __metadata: languageName: node linkType: hard +"react-test-renderer@npm:19.1.0": + version: 19.1.0 + resolution: "react-test-renderer@npm:19.1.0" + dependencies: + react-is: "npm:^19.1.0" + scheduler: "npm:^0.26.0" + peerDependencies: + react: ^19.1.0 + checksum: 10c0/34ed4a37ba8b0beb96c048de6ff28574f018a18dd1042c24f8f46142d48eb5b27f82ff7c2823d082932fd3983c5a3529ab8cc8f15191d4306df0082f9f84678f + languageName: node + linkType: hard + "react@npm:19.1.0": version: 19.1.0 resolution: "react@npm:19.1.0" @@ -17473,10 +17533,12 @@ __metadata: dependencies: "@react-native-async-storage/async-storage": "npm:^2.2.0" "@reflag/react-native-sdk": "workspace:*" + "@types/react": "npm:^19.1.0" expo: "npm:~54.0.0" react: "npm:19.1.0" react-native: "npm:0.81.5" react-native-safe-area-context: "npm:^5.6.0" + typescript: "npm:^5.8.3" languageName: unknown linkType: soft @@ -20506,6 +20568,7 @@ __metadata: resolution: "workspaces@workspace:." dependencies: "@changesets/cli": "npm:^2.29.6" + "@changesets/get-release-plan": "npm:^4.0.15" husky: "npm:^9.1.7" lerna: "npm:^10.1.1" lint-staged: "npm:^16.2.7"