Nuxt

Introduction

The Nuxt SDK combines a client and a server SDK to provide configs to the browser, to server resource handlers, and to SSR. It is intended to be used by Nuxt web applications running on modern web browsers. All modern web browsers on popular platforms should be supported.

The minimum supported version of Nuxt is 3.7.0.

Browser SDKs are tested on the latest versions of Chrome, Firefox, Safari, and Edge.

Telemetry collection within the browser uses Web Workers to aggregate and send telemetry data. If the SDK runs on older browsers without Web Workers support, config evaluation will continue to work but no telemetry data will be collected for that session.

Installation

The SDK can be installed from NPM: https://www.npmjs.com/package/@configdirector/nuxt-sdk

npm install --save @configdirector/nuxt-sdk

yarn add @configdirector/nuxt-sdk

pnpm add @configdirector/nuxt-sdk

bun add @configdirector/nuxt-sdk

Configure the Nuxt module

The Nuxt SDK requires the client SDK key for evaluation in the browser, and the server SDK key for server side rendering (SSR) and for server routes.

You can provide the keys in nuxt.config.ts:

export default defineNuxtConfig({
  //...
  modules: ["@configdirector/nuxt-sdk"],
  runtimeConfig: {
    public: {
      configdirector: {
        // You can also provide the key at runtime to match the given environment
        // via the NUXT_PUBLIC_CONFIGDIRECTOR_CLIENT_SDK_KEY environment variable
        clientSdkKey: "YOUR-CLIENT-SDK-KEY",
      },
    },
    configdirector: {
      // IMPORTANT: This is a secret, do not commit to your source repository
      // You can provide the server key at runtime via the
      // NUXT_CONFIGDIRECTOR_SERVER_SDK_KEY environment variable
      serverSdkKey: "YOUR-SERVER-SDK-KEY",
    },
  },
});

Since the server SDK key is a secret value, the recommended approach is to provide it via an environment variable:

export NUXT_CONFIGDIRECTOR_SERVER_SDK_KEY=YOUR-SERVER-SDK-KEY

The client key can also be provided via an environment variable, which overrides the key provided in: nuxt.config.ts:

export NUXT_PUBLIC_CONFIGDIRECTOR_CLIENT_SDK_KEY=YOUR-CLIENT-SDK-KEY

Additional configuration options

appName and appVersion

These options allow you to provide your application's name and version. These values can be used in targeting rules conditionals. For example, if a certain feature should only be enabled starting with a certain version of your application.

export default defineNuxtConfig({
  //...
  modules: ["@configdirector/nuxt-sdk"],
  runtimeConfig: {
    public: {
      configdirector: {
        appName: "YOUR-APP-NAME",
        appVersion: "1.0.2",
      },
    },
  },
});

logLevel

The SDK uses the consola logger provided via Nuxt. You can adjust the ConfigDirector's SDK logging level independently for both the client and server side:

export default defineNuxtConfig({
  //...
  modules: ["@configdirector/nuxt-sdk"],
  runtimeConfig: {
    public: {
      configdirector: {
        /**
         * Log level for the client/browser side of the ConfigDirector Nuxt SDK,
         * using consola's numeric levels.
         * 0 = error, 1 = warn, 2 = log, 3 = info, 4 = debug, 5 = trace.
         */
        logLevel: 4, // debug
      },
    },
    configdirector: {
      /**
       * Log level for the server side of the ConfigDirector Nuxt SDK,
       * using consola's numeric levels.
       * 0 = error, 1 = warn, 2 = log, 3 = info, 4 = debug, 5 = trace.
       */
      logLevel: 3, // info
    },
  },
});

baseUrl

The base URL used to connect to ConfigDirector services. It can be configure independently for the client and server side. This should only be provided if your environment requires you to configure a proxy server in order to connect to ConfigDirector services.

Retrieve config values

The useConfigDirectorValue composable is available to app components. On the server side, the useConfigDirectorClient returns the global server instance of the client (an instance of the Node.js SDK).

<script setup lang="ts">
const { value } = useConfigDirectorValue("my-config-key", false);
</script>

<template>
  <div>my-config-key is : {{ value }}</div>
</template>

export default defineEventHandler(async (_event) => {
  const client = useConfigDirectorClient();
  return client.getValue("my-config-key", false);
});

The value returned by the useConfigDirectorValue composable is a ShallowRef that will update whenever the config value is updated in the ConfigDirector dashboard, or if it evaluates to a different value due to targeting rules (for example, if the user context is updated). Keep in mind that it is a ShallowRef when accessing it in scripts:

<script setup lang="ts">
const { value: myConfigValue } = useConfigDirectorValue("my-config", "default value");

const someOtherDerivedValue = computed(() => `Hello ${myConfigValue.value}`);
</script>

<template>
  <div>my-config is : {{ someOtherDerivedValue }}</div>
</template>

You can also determine if the client is still initializing, so rather than transition from the default value to the evaluated value, you can show a loading state until the client is ready and config values are evaluated:

<script setup lang="ts">
const { value, loading } = useConfigDirectorValue("my-config", "default value");
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else>my-config is : {{ value }}</div>
</template>

Additionally, you can also use the useConfigDirectorStatus composable to retrieve just the status:

<script setup lang="ts">
const { loading } = useConfigDirectorStatus();
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else><SomeComponentThatUsesConfigValues /></div>
</template>

SSR config evaluation

Evaluation of config values during server side rendering (SSR) utilizes the global server instance of the ConfigDirector Node.js client. That means there are no additional network requests that take place since the server SDK evaluates targeting rules locally for any given user context.

Update the user context

<script setup lang="ts">
const { updateContext } = useConfigDirectorContext();
const { value } = useConfigDirectorValue("my-config-key", false);

const onUpdate = () => {
  updateContext({
    id: "654321",
    name: "Another User",
    traits: {
      region: "Australia",
    },
  });
};
</script>

<template>
  <div>my-config-key is : {{ value }}</div>
  <button type="button" @click="onUpdate">Update Context</button>
</template>

export default defineEventHandler(async (_event) => {
  const client = useConfigDirectorClient();
  return client.getValue("my-config-key", false, {
    id: "654321",
    name: "Another User",
    traits: {
      region: "Australia",
    },
  });
});

useConfigDirectorClient composable

In the event that you need to have access to the underlying Javascript ConfigDirectorClient instance in app components for more complex behaviors, you can access the instance via the useConfigDirectorClient composable:

<script setup lang="ts">
const { client } = useConfigDirectorClient();

// Utilize the client for more involved logic
</script>

<template>
  <div>A component with more complex usage</div>
</template>