Skip to content

feat: adopt v2 flag values in Browser, React, Vue and React Native SDKs - #791

Merged
roncohen merged 37 commits into
mainfrom
feature/browser-framework-sdk-v2
Nov 19, 2026
Merged

roncohen merged 37 commits into
mainfrom
feature/browser-framework-sdk-v2

Conversation

@roncohen

@roncohen roncohen commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Stack and review boundary

Summary

  • Adopt protocol-v2 evaluated flags and direct JSON values. Bare singular reads return Boolean/false; positional JSON defaults infer widened mutable values. Explicit null accepts arbitrary JSON. Runtime matching checks only top-level categories; old wrappers are removed.
  • Fetch values and opt-in metadata together from /flags/evaluated with atomic validation and context/version guards. Metadata-only refresh preserves bootstrap values/provenance; mutations confirm versioned evaluation and membership in one refresh.
  • Register requested-root checks immediately with buffered, identity-aware delivery. Defaults, mismatches, overrides and value-only fallbacks do not invent selections. Diagnostic/bootstrap access does not register checks.
  • Isolate v2 cache/override storage, own returned JSON/context, preserve known-good snapshots and capture cache identity before update listeners can change context. Carry forward main's initialization diagnostics, readable opt-in errors, security updates and test cleanup.
  • React and Native useFlag are non-suspending direct-value reads; useFlagSuspense explicitly waits. Vue returns refs. Tracking, feedback, loading and opt-in remain separate hooks/composables.

React Native migration

  • Native now uses workspace React v2, development version 2.0.0-next.0, and a major Changeset. This PR's next prerelease configuration plans 2.0.0-next.1, not stable 2.0.0. Its modern JSX build requires React 17+ and the React version supported by the application’s Native runtime.
  • Reexport v2 value/opt-in types and useFlagSuspense; remove legacy wrapper/remote-config types. Native shares React's optional Flags registry, including React-format declarations, rather than maintaining a second evaluator or type registry.
  • Preserve AsyncStorage, native SSE with transport polling disabled, custom adapters and default live updates. Web toolbar/automatic feedback UI default off.
  • Accept matching Node v2 bootstrap without an initial evaluation fetch; reject legacy bootstrap. Test selected-key/source/snapshot identity, defensive JSON ownership, missing/null/falsy values, versioned live updates, opt-in metadata/confirmation and offline defaults.
  • Migrate Expo and bare Native demos to direct values and separate tracking. Their typechecks and five Native compiler programs (consumer contracts, runtime fixtures and both apps) run in the new package test:ci; Native runtime tests now participate in workspace CI.
  • OpenFeature Browser remains isolated on published Browser v1. The Next.js bootstrap demo uses workspace Node v2.

Registered-default contracts

Named-interface/readonly defaults work. Registered keys constrain non-null defaults, including required/nested properties, arrays and literal unions; Suspense follows the same contract. Explicit default generics cannot bypass registered schemas. Boolean/undefined and arbitrary-JSON null semantics remain. This is not nested runtime schema validation. Built Vue refs retain public vue imports, and TypeDoc validation stays enabled.

Correctness follow-up (fdacaf0)

  • Keep object/array results from useFlag and useFlagSuspense stable by JSON content between relevant changes, with per-hook ownership and commit-only caching. Every render still performs the read for check tracking. React Native inherits the shared fix. Eight new React regressions cover effect-driven state updates, inline defaults, updates, client/key changes, checks and ownership.
  • Version opt-in metadata independently from values. Older full/metadata-only replacements cannot roll membership back, including unavailable membership. Real context changes reset freshness; same-context bootstrap request invalidation preserves it. Six new Browser regressions cover racing responses, version/provenance separation, bootstrap reapplication and context changes.
  • Both correctness threads are addressed; Node files remain identical to main.

Approved cleanup (bb9b948, 158f36b)

  • Type the React selected() fixture as (value: FlagValue, variantKey = "true"): RawFlag, removing four repeated assertions and five redundant value overrides without changing fixture data.
  • Make fallback-backed maybeFetchFlags() return a non-optional snapshot and require it in applyFetchedFlagsResult(). Remove only unreachable absence handling; raw-fetch failures remain optional and guarded, bootstrap/cache snapshot versions remain optional, and all freshness checks are preserved.
  • Extract clearOptInMetadata() for exactly the metadata map, context marker and snapshot version, replacing the three existing reset blocks in place. The stale-version guard, same-context retention and request/loading bookkeeping are unchanged. Inlining all three calls exactly reproduces the previous source.
  • Resolved the fixture/result-contract refactor threads, including later duplicate suggestions, and the subsequently approved metadata-reset-helper thread.

Fresh verification

Package Runtime tests
Evaluator 302
Node 273
Browser 269
React 27
Vue 15
React Native 15
OpenFeature Node / Browser 32 / 27
CLI / Management / Express 36 / 7 / 4
Total 1,007
  • Latest 158f36b source verification: all 1,007 workspace runtime tests and 48 Browser E2E cases across Chromium/Firefox/WebKit pass. Builds pass for 10 SDK/provider/CLI/Express projects; both Next.js example typechecks, Native compiler contracts and app typechecks, focused strict typing of the changed runtime fixtures, docs and three docs-transform tests pass. Management regeneration and Next.js production-app builds are excluded from that bounded build run. Ten new regressions failed before the fixes; the unchanged original tests passed.
  • Earlier e16293a versioned-tree verification ran the actual version command to generate 2.0.0-next.1, then passed all 993 then-existing workspace tests and 48 Browser E2E cases. That is distinct from the latest source-level run.
  • Eight release safeguard tests run in Package CI and pass again on 158f36b. The e16293a lifecycle dry run also passed them before versioning, after next versioning, during explicit prerelease exit and after stable versioning. Two ignored/private-workspace regressions failed without the Changesets backport and passed with it; both real next and stable-transition immutable installations passed.
  • Earlier Native migration verification: Android and iOS Metro bundles passed for both bare Native and Expo (JS exports, not device/emulator or native-binary acceptance; not rerun for this merge).
  • Earlier e16293a tarballs for Node, Browser, React, Vue and React Native 2.0.0-next.1 contain runtimes/declarations and rewritten workspace dependencies. A clean npm consumer installs those five local tarballs plus registry supporting dependencies, resolves one matching Browser/React dependency graph, and passes Node-to-Browser bootstrap, React SSR, Vue export checks and strict public-consumer typing across all five SDKs. Native runtime/device execution is not claimed. This does not replace the final matched CLI/packed-toolchain canary.
  • Browser client fixtures clear storage between tests to prevent cached opt-in state leaking across cases; five repeated runs passed during the earlier Native migration. Three docs-transform tests pass on this merge. A new regression verifies the v2 bootstrap demo resolves workspace Node v2; React's cross-package TypeDoc links are explicitly qualified.
  • Changed-source lint has zero warnings/errors. Full lint retains only main's generated Next.js declaration warning. Native tests emit the renderer's upstream deprecation notice. Normal commit hooks preserve the verified tree.
  • Full Management regeneration/root yarn build was not run locally because Java is absent; generated Management sources remain inherited unchanged from Node/main.

Next prerelease configuration

Commit e16293a enters Changesets' repository-wide prerelease mode with tag next. The existing automated version/publish workflow handles the SDK dependency graph; this does not depend on the separate Node-only manual workflow in #802.

The verified first release plan is:

Packages Planned version / npm tag
Node, Browser, React, Vue, React Native SDKs 2.0.0-next.1 / next
Existing queued CLI patch 1.0.5-next.0 / next
Existing queued OpenFeature Node patch 1.2.9-next.0 / next

next.1 follows the existing next.0 development manifests. Packed React/Vue dependencies point to ^2.0.0-next.1 Browser, and Native points to ^2.0.0-next.1 React. Node retains published evaluator 2.0.0; OpenFeature Browser remains pinned to published Browser v1. The existing SDKs all have stable npm releases, and these prereleases use next rather than advancing their stable latest tags.

The workflow skips all four stable-doc publication steps for prereleases and fails closed on malformed/unexpected prerelease state. Stable-doc publication resumes only on the normal stable channel; this is not the separate release-aware docs-routing redesign. The docs checkout action is updated to supported v4.

A small locked Yarn backport of Changesets #2092 prevents prerelease exit from spuriously bumping ignored/private or unversioned workspaces. Without it, @reflag/tsconfig incorrectly becomes 0.0.3 and the stable-transition install fails. The real next → explicit exit → stable versioning/installation dry run now passes while that private package stays 0.0.2.

Not active on main until this PR is merged. The existing stable version PR #796 must be regenerated with this configuration before it is merged; do not merge its old stable Node 2.0.0 plan. No npm publication, main merge or dist-tag change was performed.

Remaining release boundaries

Compatible server values/opt-in metadata/check ingestion, server-first deployment, approved saved snapshots and deployed acceptance remain required. Genuine matched-rule integration, CLI 2 review/mandatory generated-consumer CI and final versioned/packed-toolchain canary are separate work. Coordinate evaluator memoization publication/adoption separately.

Native now participates in this v2 migration; reconcile public-doc version routing that still assumes independent Native v1 before cutover. Source Native documentation is updated here. OpenFeature multivariate adoption remains separate. No device/emulator smoke, package publication, deployment, main merge, persistent service restart or shared-data mutation was performed.

@roncohen
roncohen added this pull request to stack #792 November 4, 2026 11:28
Base automatically changed from feature/multivariate-evaluator-v2 to main November 4, 2026 18:40
Keep published evaluator 2.0.0 and main's dependency updates, port ETag revalidation and initialization diagnostics to complete collections, preserve application-owned shutdown, and address the three Node migration review regressions. Keep OpenFeature and the v1 bootstrap demo isolated on published Node 1.8.3.
Preserve Browser/React/Vue v2 transport, direct values and bootstrap APIs while carrying forward main's initialization diagnostics, readable opt-in error responses, security updates and test cleanup. Keep legacy framework consumers on published v1 and validate the combined Node-to-Browser bootstrap contract.
@roncohen

Copy link
Copy Markdown
Contributor Author

Reconciled with current Node v2 and main in merge commit 793a40994e584712655bb503531ff17adcd16810. GitHub now reports mergeable / no conflicts against main. The PR remains draft; this does not merge or publish anything.

  • Merge parents: framework 9f3a0ae and Node 0809be2; main 1adfced is already inherited through Node.
  • Kept the v2 direct-value, transport, bootstrap, cache ownership and registered-default APIs. Ported main's initialization diagnostics, readable opt-in error responses, security updates and test cleanup without restoring v1 wrappers.
  • React/Vue use workspace Browser v2; the bootstrap demo uses workspace Node v2. Unchanged Native/OpenFeature Browser consumers stay isolated on published v1 dependencies.
  • Local verification: 882 workspace tests, 48 cross-browser E2E tests, three docs-transform tests, SDK/provider builds, SDK type programs, both Next.js example typechecks, immutable install, docs, formatting and scoped zero-warning lint. Full lint has only the inherited generated Next.js declaration warning. A real built Node → JSON bootstrap → built Browser probe also passes without real HTTP.
  • Full Management regeneration/root build was not run locally because Java is absent; generated Management sources are inherited unchanged from Node/main. Fresh remote CI is running.
  • All 16 existing worktrees retain their HEADs, indexes, statuses and dirty-file hashes. In particular, neither pending matched-rule patch nor the Node demo was mixed into this reconciliation.

Separate stacked memoization/guide PRs, CLI work, packed release acceptance and server/snapshot/publication gates remain separate.

@roncohen
roncohen marked this pull request as ready for review November 15, 2026 23:47
Copilot AI balanced review requested due to automatic review settings November 15, 2026 23:47

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

no actionable findings

Comment thread packages/browser-sdk/src/flag/flags.ts Resolved
Comment thread packages/node-sdk/src/client.ts Resolved

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

no actionable findings

Comment thread packages/node-sdk/test/client.test.ts Resolved
Comment thread packages/react-sdk/test/usage.test.tsx Resolved

@reflag-review reflag-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

1 actionable finding; 1 optional refactor suggestion.

Comment thread packages/browser-sdk/src/flag/flags.ts Resolved
Comment thread packages/react-sdk/test/usage.test.tsx Resolved

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

Assessed 91 changed files in 5 complete diff batches. All suggestions batches preceded independent correctness sessions.

Batch 1: Reviewed this batch’s Browser SDK protocol-v2 migration, value reads, bootstrap validation, caching, overrides, opt-in handling, and release safeguards, including surrounding code, callers, tests, and resolved discussions. No actionable P1 or P2 regression was substantiated. Review was limited to immutable repository snapshots; tests were not run.

Batch 2: No actionable P1/P2 bugs substantiated in this test-focused batch after inspecting related transport validation, caching, initialization, and feedback code. Review was read-only; tests were not run. Risk reflects the broader PR’s SDK public-contract and protocol migration.

Batch 3: Reviewed this batch’s React Native v2 integration, release/type tests, example changes, and related React/Browser implementation and build configuration. No actionable P1/P2 regression was substantiated in the supplied changed lines. Review was read-only; tests were not run. The broader v2 public API and bootstrap compatibility changes carry high integration risk.

Batch 4: Reviewed the supplied React SDK changes and related Browser SDK implementations. Found one object-valued hook regression affecting React effects. Review was read-only; no tests were executed. Risk is high because the original PR changes public SDK contracts, bootstrap compatibility, and the evaluation protocol across frameworks.

Batch 5: Reviewed this batch’s Vue composable, bootstrap loading, public type, release-channel, and dependency changes, including surrounding providers and browser-client behavior. No actionable P1/P2 regression was substantiated. Review was limited to immutable repository snapshots; tests were not run. Overall risk remains high because the PR changes core flag-value and bootstrap contracts across SDKs and prerelease distribution.

Optional refactor suggestions are labeled separately from correctness findings.

Advisory AI review; no code was changed and no tests were executed.

Comment thread packages/react-sdk/src/index.tsx Resolved
Comment thread packages/browser-sdk/src/flag/flags.ts Resolved
Comment thread packages/react-sdk/test/usage.test.tsx Resolved

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

no actionable findings

2 optional refactor suggestions.

Advisory only; no code changed or tests run.

Comment thread packages/browser-sdk/src/flag/flags.ts Resolved
Comment thread packages/react-sdk/test/usage.test.tsx Resolved

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

no actionable findings

@roncohen
roncohen enabled stacked auto-merge November 19, 2026 11:06

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

no actionable findings

2 optional refactor suggestions.

Comment thread packages/react-native-sdk/src/index.tsx Resolved
Comment thread packages/react-sdk/test/usage.test.tsx Resolved
@roncohen

Copy link
Copy Markdown
Contributor Author

Resolved the new main conflict in ca1a1ee, a normal merge of main e81c3fa into the existing feature branch (no rebase or force push).

The only conflict was the package.json resolutions block. Kept both the Changesets prerelease-exit patch and main’s get-uri/minimatch security overrides. Also retained main’s cleanly merged root/Cloudflare/Ruby lockfile updates and #809 test-reporter handling. SDK runtime sources, prerelease state, release safeguards, and publish policy are unchanged from 158f36b.

Fresh validation: root and standalone Cloudflare immutable installs; all 8 release safeguard tests; evaluator/Node/Browser/React/Vue/Native builds; Browser/React/Vue compiler programs and 311 runtime tests (269 + 27 + 15); scoped formatting, whitespace checks, and normal commit hooks pass. The earlier 1,007-test/full E2E checkpoint remains historical; it was not rerun in full for this dependency-only reconciliation. Fresh remote CI must complete.

@roncohen

Copy link
Copy Markdown
Contributor Author

Addressed both remaining unresolved suggestions in cab0697:

  • Native direct re-exports: packages/react-native-sdk/src/index.tsx now uses explicit direct runtime/type re-exports for the unchanged React API. Only the two base providers and three wrapper-used types remain locally imported. Public export names, hook identity, the shared Flags registry, and Native defaults are unchanged.
  • Reuse the bootstrap test tree: packages/react-sdk/test/usage.test.tsx now uses the same tree(flags) helper for SSR, client rendering, and rerenders, preserving props, children, and assertions.

Validation: Native build, all five Native compiler programs (including both apps), 15 Native tests, React compiler programs, 27 React tests, canonical docs generation with warnings treated as errors, three docs-transform tests, zero-warning scoped lint, formatting, whitespace checks, and normal commit hooks pass.

GitHub rejected inline thread replies because of existing pending draft reviews, so this linked comment records the fixes without modifying those drafts. Both addressed threads are being resolved. No feedback was declined; fresh remote CI is separate.

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

1 actionable finding; 1 optional refactor suggestion.

Comment thread packages/browser-sdk/src/client.ts Resolved
Comment thread packages/react-sdk/test/usage.test.tsx Resolved
@roncohen

Copy link
Copy Markdown
Contributor Author

Addressed both new review threads in b93b204:

  • Preserve undefined-only context pruning: added a shared context copier that runs the established pruning before JSON serialization. Both ReflagClient and FlagsClient use it, including construction, context updates, bootstrap application, context reads, and check-event context snapshots. Defensive ownership is retained; undefined-only objects are omitted while explicit empty objects and existing array serialization remain intact. FlagsClient compares the normalized owned context before invalidating metadata.
  • Added six regressions exercising real evaluation requests, canonical cache keys, and SSE URLs through construction, setContext, and bootstrap/no-fetch updates. They failed before the fix and now pass, including caller/returned-context mutation isolation.
  • Share the fixed-client test wrapper: extracted clientProvider(client) and reused it in all five fixed-client hook setups. The client-replacement closure and default-loading Suspense/opt-in wrappers remain unchanged.

Validation: 332 runtime tests (275 Browser, 27 React, 15 Vue, 15 Native), all four SDK builds, their standard type-test programs (including both Native apps), docs regeneration, three docs-transform tests, scoped zero-warning lint, formatting, whitespace checks, and normal commit hooks passed.

Supplemental compiler checks: Browser source/tests also passed with ES2020 (the untouched bigint fixture does not compile under the base config target), and React source/tests passed with a dedicated bundler-resolution config. An ad hoc check of the unspecialized React base config includes separately configured demos and encounters existing Next.js alias/type/config errors; those unrelated configurations were not changed. The full workspace suite and E2E suite were not rerun for this fix.

No comments were declined. This linked comment records the fixes without modifying the existing pending review drafts; both addressed threads are being resolved.

@reflag-review reflag-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Risk: high

no actionable findings

@roncohen
roncohen added this pull request to the merge queue Nov 19, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 19, 2026
@roncohen
roncohen added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 1716cae Nov 19, 2026
9 checks passed
@roncohen
roncohen deleted the feature/browser-framework-sdk-v2 branch November 19, 2026 14:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants