{"id":15675,"library":"launchdarkly-vue-client-sdk","title":"LaunchDarkly Vue Client SDK","description":"The LaunchDarkly Vue Client SDK provides seamless integration of feature flags into Vue.js applications, specifically supporting Vue 3.2 and newer versions. As of `2.5.0`, it offers a robust solution for dynamically managing features, building upon the core LaunchDarkly JavaScript SDK. Key differentiators include first-class support for Vue's Composition API through reactive hooks (like `useFlags` and `useLDClient`) and a dedicated Vue plugin for easy initialization. The SDK sees frequent releases, typically every 1-3 months, ensuring compatibility with the latest Vue and LaunchDarkly platform features. It is designed for client-side environments, requiring a client-side ID for authentication and specific flag configurations to ensure availability.","status":"active","version":"2.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/launchdarkly/vue-client-sdk","tags":["javascript","launchdarkly","launch","darkly","vue","vuejs","sdk","bindings","typescript"],"install":[{"cmd":"npm install launchdarkly-vue-client-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add launchdarkly-vue-client-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add launchdarkly-vue-client-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for core Vue.js functionality.","package":"vue","optional":false}],"imports":[{"note":"The official documentation indicates `LDPlugin` for direct import and use with `app.use()`. Some older examples or community articles might refer to `LaunchDarklyVue` as a default export, but `LDPlugin` is the canonical named export for the plugin itself.","wrong":"import LaunchDarklyVue from 'launchdarkly-vue-client-sdk'","symbol":"LDPlugin","correct":"import { LDPlugin } from 'launchdarkly-vue-client-sdk'"},{"note":"Provides all feature flags for the current context as a reactive object, typically used within Vue's Composition API `setup` hook or `<script setup>`.","symbol":"useFlags","correct":"import { useFlags } from 'launchdarkly-vue-client-sdk'"},{"note":"Provides direct access to the underlying LaunchDarkly JavaScript client instance, allowing for more advanced interactions like `track` or `identify`. Must be used within Vue's Composition API `setup` hook or `<script setup>`.","symbol":"useLDClient","correct":"import { useLDClient } from 'launchdarkly-vue-client-sdk'"},{"note":"Provides a single feature flag's value as a reactive `ref`, allowing for fine-grained reactivity and automatic re-rendering upon flag changes. It is recommended for accessing individual flags.","symbol":"useLDFlag","correct":"import { useLDFlag } from 'launchdarkly-vue-client-sdk'"},{"note":"Type definition for a LaunchDarkly context object, re-exported for convenience from the underlying JavaScript SDK. Essential for strongly typing context definitions.","symbol":"LDContext","correct":"import { LDContext } from 'launchdarkly-vue-client-sdk'"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport { LDPlugin, LDContext, useLDFlag } from 'launchdarkly-vue-client-sdk';\n\n// It's best practice to load your client-side ID from environment variables.\n// For Vite, use import.meta.env.VITE_LD_CLIENT_SIDE_ID\n// For other bundlers or Node.js, use process.env.LD_CLIENT_SIDE_ID\nconst clientSideId = process.env.VITE_LD_CLIENT_SIDE_ID ?? 'YOUR_CLIENT_SIDE_ID'; // Replace with your actual Client-side ID\n\nconst context: LDContext = {\n  kind: 'user',\n  key: 'example-user-key',\n  name: 'Example User',\n  // Custom attributes can be added here\n  _meta: { privateAttributes: ['email'] }, // Example: Mark 'email' as private\n};\n\nconst app = createApp(App);\n\n// Initialize the LaunchDarkly Vue plugin\napp.use(LDPlugin, {\n  clientSideId,\n  context,\n  // Optional: Add further options for the underlying JS SDK\n  options: {\n    streaming: true, // Enables real-time flag updates\n    // logger: LaunchDarkly.basicLogger({ level: 'debug' }), // Uncomment for debug logs\n  },\n});\n\napp.mount('#app');\n\n// App.vue\n<script setup lang=\"ts\">\nimport { ref, watchEffect } from 'vue';\nimport { useLDClient, useLDFlag } from 'launchdarkly-vue-client-sdk';\n\n// Use useLDFlag for a specific flag, providing a fallback value\nconst myFeatureEnabled = useLDFlag('my-boolean-feature', false);\n\n// Access the underlying LDClient for advanced operations like tracking events\nconst ldClient = useLDClient();\n\nconst trackCustomEvent = () => {\n  if (ldClient) {\n    ldClient.track('button-clicked', { customData: 'from-vue' });\n    console.log('Custom event tracked!');\n  }\n};\n</script>\n\n<template>\n  <div>\n    <h1>LaunchDarkly Vue SDK Demo</h1>\n    <p>Is 'my-boolean-feature' enabled? <strong>{{ myFeatureEnabled ? 'Yes' : 'No' }}</strong></p>\n    <button @click=\"trackCustomEvent\">Track Button Click</button>\n\n    <p v-if=\"myFeatureEnabled\">This content is only visible if 'my-boolean-feature' is ON!</p>\n    <p v-else>This content is visible if 'my-boolean-feature' is OFF!</p>\n  </div>\n</template>\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the LaunchDarkly Vue SDK using `LDPlugin`, configure an `LDContext`, and then consume a feature flag reactively within a Vue component using the `useLDFlag` composable. It also shows how to access the underlying `LDClient` for custom event tracking."},"warnings":[{"fix":"Ensure you are using the 'Client-side ID' found in your LaunchDarkly project settings. Do not embed a server-side SDK key in client-side code.","message":"The SDK requires a 'Client-side ID' for initialization, not an 'SDK key' or 'Mobile key'. Using an incorrect key type (e.g., a server-side SDK key) will prevent the client from initializing correctly and could lead to unexpected behavior or security issues.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Navigate to the flag's settings in the LaunchDarkly UI and ensure the 'Make this flag available to client-side SDKs' option is checked.","message":"For any feature flag to be available to the Vue SDK, the 'Make this flag available to client-side SDKs' checkbox must be enabled on that flag's settings page in the LaunchDarkly dashboard. If not enabled, the SDK will receive the flag's fallback value.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Update error handling for `waitForInitialization` to catch promise rejections if you are using a timeout. If no timeout is specified, the promise still waits indefinitely.","message":"The `waitForInitialization` method's behavior changed in version 2.2.0. If a timeout is specified, the returned promise will now be rejected after the timeout elapses if the client has not finished initializing. Previously, it would only resolve or reject upon completion or failure without a timeout.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Ensure that any `metricValue` passed to the `track` method is a valid number. For non-numeric custom data, pass it within the `data` object of the event properties.","message":"The `track` method now validates that the `metricValue` parameter is a number since version 2.2.0. If a non-numeric value is provided for `metricValue`, a warning will be logged, and the event might not be tracked as expected.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Upgrade your Vue project to Vue 3.2 or later. For Vue 2 projects, consider using the LaunchDarkly JavaScript SDK directly or community-developed wrappers compatible with Vue 2.","message":"This SDK exclusively supports Vue 3.2 and newer versions. Attempts to use it with Vue 2.x projects will result in compatibility errors and unexpected behavior.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace all instances of `LDUser` with `LDContext` when defining your entities for flag evaluation. Ensure your context object explicitly defines a `kind` attribute.","message":"Starting with version 2.0.0, the SDK only operates on 'contexts' instead of 'users'. Any existing code from 1.x versions that used `LDUser` must be updated to use `LDContext`. While the underlying JS SDK might convert `LDUser` to `LDContext` implicitly, it's strongly recommended to explicitly use `LDContext` for correct behavior and full feature access.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure your project is running Vue 3.2 or newer and that `app` is a valid Vue 3 application instance created with `createApp()`.","cause":"Attempting to use the SDK's Vue plugin with a Vue 2 application or an improperly created Vue 3 app instance.","error":"TypeError: app.use is not a function"},{"fix":"Verify that the `clientSideId` passed to `LDPlugin` is your correct LaunchDarkly Client-side ID (not an SDK key). Also, confirm that the feature flag in question has the 'Make this flag available to client-side SDKs' option checked in your LaunchDarkly dashboard.","cause":"The LaunchDarkly client failed to initialize due to an invalid `clientSideId`, or the specific feature flag is not enabled for client-side SDKs in the LaunchDarkly dashboard.","error":"LaunchDarkly client not initialized or flag not found (fallback value returned unexpectedly)."},{"fix":"When defining your `LDContext`, ensure you explicitly specify custom attributes or use type assertions if your context has a known structure. For example: `{ kind: 'user', key: 'example', email: 'test@example.com' } as LDContext & { email: string }`.","cause":"Attempting to access a specific attribute like 'email' directly on a generic `LDContext` type without specifying its structure or `kind` property in TypeScript.","error":"Property 'email' does not exist on type 'LDContext'."},{"fix":"Ensure all LaunchDarkly composables (`useLDFlag`, `useFlags`, `useLDClient`, etc.) are invoked directly within the `<script setup>` block of a Vue component or inside the `setup()` method of an options API component.","cause":"The `useLDFlag` (or other `useLD...` composables) is being called outside of a Vue Composition API `setup` function or a `<script setup>` block.","error":"Error: useLDFlag must be called from within a setup function or script setup."}],"ecosystem":"npm"}