@mftc/nuxt-launch-darkly

A Nuxt module for interacting with the Launch Darkly SDK

This module is under heavy development so expect breaking changes.

Features

• 🌈 Composable for Composition API support
• ⚡️ Adds REST endpoints for custom integrations
• 💯 Nuxt 3

Setup

1. Install @mftc/nuxt-launch-darkly

npm install @mftc/nuxt-launch-darkly or # yarn add @mftc/nuxt-launch-darkly

2. Add it as a buildModule in nuxt.config.ts and configure it with your Launch Darkly server-side SDK key. The sdkKey should go in privateRuntimeConfig since the Launch Darkly SDK Key needs to be kept private.

export default defineNuxtConfig({
  buildModules: ['@mftc/nuxt-launch-darkly'],
  privateRuntimeConfig: {
    launchDarkly: {
      sdkKey: process.env.LD_SDK_KEY
    }
  },
  // optional
  launchDarkly: {
    apiPath: '/api/launch-darkly', // customisable api path: default '/api/launch-darkly'
    logLevel: 'info' // 'debug' | 'info' | 'warn' | 'error' | 'none': default 'info'
  }
})

Usage

🧩 Composable

<script setup>
  const USER = {
    key: 'UNIQUE_USER_ID', // required
    email: '[email protected]',
    firstName: 'Jane',
    lastName: 'Doe'
  }
  const FLAG_KEY = 'my-feature-flag'

  const { getAllVariations, getVariationByKey, getVariationDetail, identifyUser, track } = useLaunchDarkly()

  // get all variations for the provided user
  const allFlags = getAllVariations(USER)
  // get a specified variation for the provided user
  const singleFlag = getVariationByKey(USER,   FLAG_KEY)
  // get a specified variation for the provided user with detail
  const singleFlagDetail = getVariationDetail(USER,   FLAG_KEY)
  // get multiple variations
  // if you are using any of the functions provided by the
  // composable more than once per component, don't forget to
  // pass a unique key to ensure that data fetching can be
  // properly de-duplicated across requests
  const pickFlags = getAllVariations(USER, [FLAG_KEY, 'second-key', 'third-key'], 'unique-key')

  // manually identify a user.
  // note: this is done automatically for you when calling getAllVariations, getVariationByKey and getVariationDetail
  const identify = () => identifyUser(USER)

  // track custom data
  // myKey is the name of the custom metric you want to track
  const dataToTrack = {
    myKey: {
      arr: [1, 'foo'],
      nested: {
        a: 1,
        b: {
          key: 'bar'
        }
      }
    },
    metricValue: 1
  }
  const trackData = () => track(USER, dataToTrack)

</script>

🌀 REST Endpoint

This module exposes the REST endpoints that are used by the composable internally. This could be useful if you wanted to get all the flags on app init and save them to the store for example.

The module exposes two endpoints:

1. ${apiPath}/flags
2. ${apiPath}/user

Query Parameters:

key: string // required
email?: string
firstName?: string
lastName?: string

?key=xxx-xxx&[email protected]&firstName=Jane&lastName=Doe

These query parameters are valid for all requests. key is the only required parameter.

The API path will default to /api/launch-darkly but you can set a custom path in the launchDarkly config in nuxt.config.ts. See the setup section for details

/flags

Get all variants

LDClient.allFlagsState

GET /api/launch-darkly/flags?{query-params}

Get single variant

LDClient.variation

GET /api/launch-darkly/flags/flag-key?{query-params}

Get single variant with detail

LDClient.variationDetail

GET /api/launch-darkly/flags/flag-key/detail?{query-params}

/user

Identify

LDClient.identify

GET /api/launch-darkly/user/identify?{query-params}

Track

LDClient.track

curl -X POST "/api/launch-darkly/user/track?{query-params}" -H "Content-Type: application/json" -d '{"myKey":{"arr":[1,"foo"],"nested":{"a":1,"b":{"key":"bar"}}},"metricValue":1}'

Development

• Create a .env file in the playground directory and add these variables:

LD_SDK_KEY= # with the value of a Launch Darkly server-side SDK Key.
EMAIL= # email address of a user captured by LD (optional)
USER_KEY= # the unique key of a user captured by LD
FIRST_NAME= # first name
LAST_NAME= # last name

• Run npm run prepare:playground to generate type stubs.
• Use npm run play to start playground in development mode.