Vue SDK reference

Overview

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

Getting started

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

To install the Vue SDK, you need your LaunchDarkly environment's client-side ID.

To find and copy your LaunchDarkly client-side ID:

1. Navigate to the Account settings page.
2. Click the Projects tab.
3. Click the name of your project. The Environments tab appears.
4. Click the environment's client-side ID to copy it to your clipboard.

Install the Vue SDK using either npm or yarn:

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

After you install the dependency, add the LaunchDarkly plugin to your Vue app. Typically you do this in main.js:

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

Configuring the Vue SDK

The SDK provides a Vue plugin that you can add to your app. 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 Initializing the client. To learn more about the available configuration options, read LDPluginOptions.

Using the plugin

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

Initializing the LaunchDarkly client

The SDK automatically initializes the LaunchDarkly client if you provide a clientSideID, and do not use the deferInitialization option. Otherwise, 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 your user at plugin load time and need to defer initialization until you do, you can use the deferInitialization option.

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, read the API documentation for ldInit.

Use ldReady to check when the LaunchDarkly client has finished initializing. This is returned by ldInit. You can also retrieve it independently with useLDReady. ldReady is a ref, so to access its value outside of a template you need to use ldReady.value.

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

Retrieving flag values with the client

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.

Example usage:

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

The Vue SDK automatically subscribes to flag change events with useLDFlag, and your component re-renders automatically when flag changes occur. 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(). If you do not want flag updates streamed to your application, you can disable this by including the streaming: false option when loading the plugin or calling ldInit.

To learn more, read the API documentation for useLDFlag.

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

Here is an example:

import { useLDClient } from 'launchdarkly-vue-client-sdk'
const ldClient = useLDClient()
const allFlags = ldClient.allFlags()
COPY

Example app

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

git clone git@github.com:launchdarkly/vue-client-sdk.git
cd vue-client-sdk
npm i
npm start
COPY