Vue SDK reference

Overview

This topic documents how to get started with the Vue SDK.

Get started

After you complete the Get started process, follow these instructions to start using the LaunchDarkly SDK in your Vue project:

• Understand version compatibility
• Install the SDK
• Configure the SDK
• Initialize the client and context
• Set the initialization timeout
• Retrieve flag values for the context

Understand version compatibility

The LaunchDarkly Vue SDK only works with Vue 3:

• Vue SDK 2.0 requires Vue 3.2 or newer
• Vue SDK 1.x requires Vue 3 or newer

For Vue 2 projects, you can use the JavaScript SDK directly, or a community-developed package such as vue-ld.

The Vue SDK is based on the JavaScript SDK. The Vue SDK builds on LaunchDarkly's JavaScript SDK to provide a better integration for use in Vue applications. As a result, much of the JavaScript SDK functionality is also available for the Vue SDK to use. For a complete client-side JavaScript SDK reference, read JavaScript SDK reference.

Install the SDK

To install the Vue SDK, you need your LaunchDarkly environment's client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly.

Install the Vue SDK using either npm or yarn:

npm install --save launchdarkly-vue-client-sdk
COPY

Configure the SDK

The SDK provides a Vue plugin that you can add to your app. After you install the SDK, add the LaunchDarkly plugin to your Vue app. Typically you do this in main.js.

Here's how:

import { createApp } from 'vue'
import App from './App.vue'
import { LDPlugin } from 'launchdarkly-vue-client-sdk'
const clientSideID = 'client-side-id-123abc'
const app = createApp(App)
app.use(LDPlugin, { clientSideID })
app.mount('#app')
COPY

You can pass configuration options to the plugin when it loads, or to the ldInit function if you are using the deferInitialization option. To learn more, read Initialize the client and context, below.

The plugin exposes the LaunchDarkly client, as well as some convenience functions. The plugin uses the Vue provide/inject API to do this, which means these convenience functions will only work when run within Vue's setup hook or <script setup>. To learn more, read Provide/Inject.

Initialize the client and context

After you configure the Vue SDK and plugin, configure and initialize the LaunchDarkly client and the context. To create a client instance, you need your LaunchDarkly environment's client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly. The context provides information about the end user who is encountering feature flags in your application.

The SDK automatically initializes the LaunchDarkly client if you provide a clientSideID and do not use the deferInitialization option.

If you do use the deferInitialization option, then you will need to initialize the LaunchDarkly client manually with ldInit, which accepts the same options as the plugin. For example, if you do not know the context at plugin load time and need to defer initialization until you do, you can use the deferInitialization option.

In the App.vue using the v2 Vue SDK, you initialize a context. In the v1.x example, you initialize a user. Here's how:

import { createApp } from 'vue'
import App from './App.vue'
import { LDPlugin } from 'launchdarkly-vue-client-sdk'
const app = createApp(App)
app.use(LDPlugin, { clientSideID: 'client-side-id-123abc', deferInitialization: true })
app.mount('#app')
COPY

To learn more about the available configuration options, read LDPluginOptions. To learn more about initialization, read ldInit.

To find out when the client has finished initialize, use ldReady. ldReady is a ref, so to access its value outside of a template you need to use ldReady.value.

ldReady is returned by ldInit. Alternatively, you can retrieve ldReady independently using useLDReady.

Here's how:

<script setup lang="ts">
  import { useLDReady } from 'launchdarkly-vue-client-sdk'
  const ldReady = useLDReady()
</script>
<template>
  <div v-if="ldReady">... content that uses LaunchDarkly ...</div>
  <div v-else>LaunchDarkly client initializing...</div>
</template>
COPY

Set the initialization timeout

You can set the initialization timeout using the ldClient.waitForInitialization function. We recommend setting a client initialization timeout of five seconds or fewer. Here's how:

<script setup>
import { ldInit } from 'launchdarkly-vue-client-sdk'
const [ldReady, ldClient] = ldInit({ user: { key: 'user-key-123abc', name: 'Sandy' } })
// specifies a 5s timeout.
ldClient.waitForInitialization(5).catch((error) => {
  if (error?.name.toLowerCase().includes('timeout')) {
    console.log(`===== timeout error: ${error}`)
  } else {
    console.log(`===== other init error: ${error}`)
  }
})
</script>
<template>
  <div v-if="ldReady">LaunchDarkly initialized.</div>
  <div v-else>LaunchDarkly initializing.</div>
</template>
COPY

Retrieve flag values for the context

Use useLDFlag to access a single flag value by key. It returns a readonly ref for the value of a flag. If you are using TypeScript, the ref's type can be inferred from the type of the fallback value provided to useLDFlag. To learn more about Vue refs, read ref in the Vue.js documentation.

Here's how:

<script setup lang="ts">
  import { useLDFlag } from 'launchdarkly-vue-client-sdk'
  const featureFlagKey = 'my-boolean-flag'
  const myFlagValue = useLDFlag(featureFlagKey, false /* fallback flag value */)
</script>
<template>
  Feature flag "{{ featureFlagKey }}" has value "{{ myFlagValue }}".
</template>
COPY

The Vue SDK automatically subscribes to flag change events with useLDFlag, which opens a streaming connection. Then, your component re-renders automatically when flag changes occur.

In some cases, streaming may not be necessary. For example, if you reload your entire application on each update, you will get all the flag values again when the client is re-initialized. If you do not want flag updates streamed to your application, use the streaming: false option when you load the plugin or when you call ldInit.

In other cases, streaming may be required. If you call useLDFlag, the SDK automatically opens a streaming connection. This is a benefit of useLDFlag as compared with getting flag values using the underlying JavaScript SDK, for example with ldClient.variant() or ldClient.allFlags().

To learn more, read useLDFlag.

You may also access the LaunchDarkly client with useLDClient, the LDClient object from the underlying JavaScript SDK.

Here is an example:

<script setup>
import { useLDClient } from 'launchdarkly-vue-client-sdk'
const [ldReady] = ldInit({ clientSideID, context })
const ldClient = useLDClient()
</script>
<template>
  <div v-if="ldReady">
    <p>All flags: {{ JSON.stringify(ldClient.allFlags()) }}</p>
  </div>
  <div v-else>LaunchDarkly client initializing...</div>
</template>
COPY

Example app

An example app is included in launchdarkly/vue-client-sdk.