diff --git a/packages/sdk/vue/README.md b/packages/sdk/vue/README.md index e219ded0e6..b0bd50b353 100644 --- a/packages/sdk/vue/README.md +++ b/packages/sdk/vue/README.md @@ -6,12 +6,6 @@ [![NPM][vue-sdk-dm-badge]][vue-sdk-npm-link] [![NPM][vue-sdk-dt-badge]][vue-sdk-npm-link] -> [!CAUTION] -> This SDK is in pre-release and not subject to backwards compatibility -> guarantees. The API may change based on feedback. -> -> Pin to a specific minor version and review the [changelog](CHANGELOG.md) before upgrading. - ## Getting started Refer to the [SDK documentation](https://launchdarkly.com/docs/sdk/client-side/vue) for instructions on getting started with using the SDK. diff --git a/packages/sdk/vue/temp_doc/CORE.md b/packages/sdk/vue/temp_doc/CORE.md new file mode 100644 index 0000000000..2be0ca777f --- /dev/null +++ b/packages/sdk/vue/temp_doc/CORE.md @@ -0,0 +1,199 @@ +# Vue SDK core doc changes (v2 -> v3) + +Tracks what needs to change in the live language reference page, +, now that the SDK has moved from +`launchdarkly-vue-client-sdk` (old repo: `launchdarkly/vue-client-sdk`) to +`@launchdarkly/vue-client-sdk` v3 in `js-core`. Not a draft of the replacement page -- a change +list to work from when editing the real `.mdx` source in `ld-docs-private`. Structured against the +canonical layout in the [[sdk-language-guide]] skill (see +`fern/topics/sdk/client-side/javascript/index.mdx` as the reference example), so items below also +call out where the current page's structure diverges from that canonical layout independent of the +v2->v3 rename. + +Current-page content below is taken from a live fetch of the page (2026-07-09); exact admonition +types (Note vs. Warning vs. Tip) couldn't be confirmed from the rendered page and need checking +against the real `.mdx` source once this is edited in `ld-docs-private`. + +## Structural changes (independent of the v3 rename) + +The current page nests `Understand version compatibility` as an `### ` under `## Get started`. +The canonical template puts environment/runtime-support content in its own top-level section +(`## Browser support`, `## Runtime requirements`, etc.) placed *before* `## Get started`, not +nested inside it. Recommend pulling this out into a new `## Runtime requirements` section. + +The current page has no `## Supported features` section at all. This is always the last section +per the template. Needs to be added (see below). + +The current page has no `## Shut down the client` section. `LDVueClient` extends the base +`LDClient`, which exposes `close(): Promise`, so this section is addable now regardless of +the v3 migration. + +The current page folds flag-change subscription behavior into the `Retrieve flag values for the +context` prose rather than giving it its own sibling section (`## Subscribe to flag changes`), +unlike the JS SDK's page. Lower priority than the other gaps since the Vue composables +auto-subscribe by default, but worth adding once `useLDClient()` access is documented, since that +exposes raw `client.on('change', ...)` for advanced use. + +The `## Get started` section has no roadmap bullet list under the intro sentence (the canonical +example links to `#install-the-sdk`, `#initialize-the-client`, etc. right after +`/home/getting-started`). Needs to be added once the H3s below are finalized. + +## SDK quick links callout + +| Row | Current (v2.x) | Required for v3 | +|---|---|---| +| SDK API documentation | `https://launchdarkly.github.io/vue-client-sdk/` | Likely `https://launchdarkly.github.io/js-core/packages/sdk/vue/docs/`, matching the browser SDK's pattern (`.../packages/sdk/browser/docs/`) -- **unverified, confirm once typedoc publishes for this package** | +| Supported SDK Versions | `../concepts/supported-versions#vue-sdk` | Unchanged, anchor should still resolve | +| GitHub repository | `https://github.com/launchdarkly/vue-client-sdk` | `https://github.com/launchdarkly/js-core/tree/main/packages/sdk/vue` (confirmed via `package.json` `homepage` field) | +| Sample application | `.../vue-client-sdk/tree/main/example` | `https://github.com/launchdarkly/js-core/tree/main/packages/sdk/vue/examples/getting-started` (confirmed exists at that path; there are also feature-specific examples under `examples/features/` -- e.g. `data-saving-mode`, `identify-eval-count` -- worth a short mention alongside the primary sample link, following the pattern other js-core SDK pages use for feature examples) | +| Published module | npm `launchdarkly-vue-client-sdk` | npm `@launchdarkly/vue-client-sdk` | + +## Runtime requirements (new top-level section, or keep as `### ` -- see Structural changes) + +Current text: "Vue SDK 2.0 requires Vue 3.2 or newer" / "Vue SDK 1.x requires Vue 3 or newer." For +Vue 2 users, recommends the JS SDK directly or the community `vue-ld` package. + +Required change: state "Vue SDK 3.0 requires Vue 3.3 or newer" (peer dep bumped `^3.2.36` -> +`^3.3.0`; confirmed in `packages/sdk/vue/package.json`). The reactive-flag-key feature (`toValue`, +`MaybeRefOrGetter`) is why the floor moved to 3.3. Keep the Vue-2/`vue-ld` guidance as-is -- +unaffected by this migration. + +## Install the SDK + +Current install commands reference `launchdarkly-vue-client-sdk`; update to +`@launchdarkly/vue-client-sdk`. Optional observability/session-replay plugin install commands are +unchanged (`@launchdarkly/observability`, `@launchdarkly/session-replay`). + +Current text says the plugins "require Vue SDK version 2.4 or later." **Open question for docs +team**: what's the right minimum-version phrasing for a fresh v3 package? Plugins pass through via +the renamed `ldOptions` field from the first v3 release, so there's no natural version gate the way +there was within the 2.x line -- may be simplest to drop the version qualifier entirely for v3. + +## Configure the SDK + +Current text and code sample reference `LDPlugin`, `app.use(LDPlugin, { clientSideID, ... })`, and +a nested `options` field (holding `plugins`). All three change: + +- `LDPlugin` -> `LDVuePlugin` +- `options: { plugins: [...] }` -> `ldOptions: { plugins: [...] }` +- Current text: "config can be passed to the plugin or to `ldInit`" -- `ldInit` no longer exists in + v3, remove this clause. Deferred initialization in v3 is `deferInitialization: true` plus calling + `client.start()` yourself later via `useLDClient()` (see Client initialization section below). + +Also worth adding here: v3 has a second, provider-component way to configure the SDK +(`createLDProvider`), not just the plugin. The current page only documents the plugin pattern. At +minimum this section should note the provider exists and link to where it's documented (its main +advantage over the plugin is slot-based gating on initialization state -- see "Determine when the +client is ready" below). + +Client-side ID / dev-server guidance (client-side IDs not secret, `ldcli` dev-server on +`localhost:8765` using project key instead of client-side ID) is unrelated to the SDK's own API and +should carry over unchanged. + +## Initialize the client and context + +Current text explains auto-init unless `deferInitialization`, recommends +`waitForInitialization()` with a <=5s timeout, and shows a ` + + +``` + + + + +```vue + + + +``` + + + + +To replicate the v2.x boolean, derive it with `computed`: + +```ts +const status = useInitializationStatus(); +const isReady = computed(() => status.value.status === 'complete'); +``` + +## Flag evaluation changes + +In v2.x, the generic `useLDFlag(key, defaultValue)` composable, backed by the `LD_FLAG` injection key, evaluated any flag type through a type parameter. + +In v3.0, `useLDFlag` and `LD_FLAG` are both removed. Flag evaluation now has typed composables: `useBoolVariation`, `useStringVariation`, `useNumberVariation`, and `useJsonVariation`. Each accepts the same `key` and `defaultValue` parameters; the return type is inferred from the composable name rather than a type parameter. + + + + +```vue + +``` + + + + +```vue + +``` + + + + +Each typed composable also has a `*VariationDetail` counterpart that returns the full evaluation detail, including the reason and variation index. This has no v2.x equivalent: + + + + +```ts +import { useBoolVariationDetail } from '@launchdarkly/vue-client-sdk'; + +const detail = useBoolVariationDetail('my-feature', false); +// detail.value.value -> boolean +// detail.value.reason -> LDEvaluationReason +// detail.value.variationIndex -> number | null +``` + + + + +In v3.0, every variation composable also accepts a reactive key, either a `Ref` or a getter function, so a component can switch which flag it evaluates at runtime without unmounting: + + + + +```ts +const flagKey = ref('feature-a'); +const enabled = useBoolVariation(flagKey, false); + +flagKey.value = 'feature-b'; // `enabled` re-evaluates automatically +``` + + + + +## Client access changes + +In v2.x, `useLDClient()`, backed by the `LD_CLIENT` injection key, returned the base `LDClient` from the underlying JavaScript SDK. + +In v3.0, `LD_CLIENT` is removed, and `useLDClient()` returns `LDVueClient`, a superset of `LDClient` that adds `getInitializationState()`, `getInitializationError()`, `onContextChange()`, `onInitializationStatusChange()`, and `isReady()`. All existing `LDClient` methods remain available. + + + + +```ts +import { useLDClient } from '@launchdarkly/vue-client-sdk'; +import type { LDVueClient } from '@launchdarkly/vue-client-sdk'; + +const client: LDVueClient = useLDClient(); +await client.identify({ kind: 'user', key: 'new-user' }); +``` + + + + +```ts +import { useLDClient } from 'launchdarkly-vue-client-sdk'; +import type { LDClient } from 'launchdarkly-vue-client-sdk'; + +const client: LDClient = useLDClient(); +await client.identify({ kind: 'user', key: 'new-user' }); +``` + + + + +## Running multiple LaunchDarkly environments + +Version 3.0 adds `createLDVueInstanceKey()`, which creates a Vue `InjectionKey` you can pass to a provider or plugin's `injectionKey` option and to any composable's optional `injectionKey` parameter. This lets you run more than one LaunchDarkly environment in the same application. This has no v2.x equivalent. + + + + +```ts +import { + createLDVueInstanceKey, + createLDProvider, + useBoolVariation, +} from '@launchdarkly/vue-client-sdk'; + +const experimentKey = createLDVueInstanceKey(); + +const ExperimentProvider = createLDProvider('experiment-client-id', context, { + injectionKey: experimentKey, +}); + +// In a child component: +const inExperiment = useBoolVariation('experiment-flag', false, experimentKey); +``` + + + + +## Identifying supported Vue versions for the 3.0 SDK + +The Vue SDK 3.0 requires Vue 3.3 or newer, up from Vue 3.2.36 in the 2.x line. The reactive flag keys described in [Flag evaluation changes](#flag-evaluation-changes) use Vue's `toValue` and `MaybeRefOrGetter`, which were introduced in Vue 3.3. diff --git a/release-please-config.json b/release-please-config.json index f155f7a0a2..0c32269931 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -421,9 +421,7 @@ ] }, "packages/sdk/vue": { - "bump-minor-pre-major": true, - "prerelease": true, - "prerelease-type": "beta", + "release-as": "3.0.0", "extra-files": [ "src/client/LDVueClient.ts", {