@flagdashio/vue

Official Vue 3 bindings for FlagDash: feature flags, remote config, AI configs, translations and experiments, with live updates.

Composables re-evaluate on their own when a flag changes in the dashboard — nothing to poll, nothing to reload.

Installation

npm install @flagdashio/vue

Requires Vue 3.3+.

Setup

import { createApp } from "vue";
import { createFlagDash } from "@flagdashio/vue";
import App from "./App.vue";

const flagdash = createFlagDash({
  sdkKey: import.meta.env.VITE_FLAGDASH_SDK_KEY,
  realtime: true,
});

createApp(App).use(flagdash).mount("#app");

The composable shape

Every value composable returns the same AsyncValue<T>:

{
  value: Ref<T>;            // the flag value, starting at your default
  isLoading: Ref<boolean>;
  error: Ref<Error | null>;
  refresh(): Promise<void>;
}

In <script setup> you unwrap refs as usual; in a template, remember these are plain objects holding refs, so it is checkout.value.value.

Feature flags

<script setup lang="ts">
import { useFlag, useFlagDetail } from "@flagdashio/vue";

const checkout = useFlag("checkout-v2", false, {
  user: { id: "user_123", plan: "pro" },
});

// Why did it resolve that way?
const detail = useFlagDetail("checkout-v2", false, { user: { id: "user_123" } });
</script>

<template>
  <p v-if="checkout.isLoading.value">Loading…</p>
  <CheckoutV2 v-else-if="checkout.value.value" />
  <CheckoutV1 v-else />
</template>

Key, default and context all accept a ref, a getter or a plain value — pass a ref and the flag re-evaluates when it changes:

const userId = ref("alice");
const banner = useFlag("beta-banner", false, () => ({ user: { id: userId.value } }));

userId.value = "bob";  // re-evaluates

Give the context a user id whenever you want a stable answer. Percentage rollouts and A/B variations hash it, so a context without one re-rolls on every evaluation by design.

Remote config

const limit = useConfig("rate_limit", 100);

AI configs

Prompts, agents, skills and rules, editable without a deploy.

const agent = useAiConfig("support-agent.md");
const files = useAiConfigs();

Translations

const greeting = useTranslation("checkout.greeting", "fr", "Hello", {
  name: "Alice",
});

The key is namespace.message; {placeholders} come from the variables object.

Experiments

<script setup lang="ts">
import { useExperiment, useExperimentMetric } from "@flagdashio/vue";

const experiment = useExperiment("checkout-redesign", { user: { id: "user_123" } });
const track = useExperimentMetric();

function onPurchase() {
  track({
    experimentKey: "checkout-redesign",
    eventName: "purchase",
    userId: "user_123",
    value: 42.5,
  });
}
</script>

Reaching the client directly

import { useFlagDash } from "@flagdashio/vue";

const { client, isReady, error } = useFlagDash();

isReady and error are refs tracking the underlying client, which is useful for a global loading state or an error banner. client is the full @flagdashio/sdk instance if you need something the composables do not cover.

Security

Ship an environment-scoped client key with read scopes only. Never put a pat_ token, or any key with write scopes, in a browser bundle — anything in the bundle is readable by anyone who loads the page.

A client key never returns targeting rules, so the browser cannot see who else you are targeting.

License

MIT

Session replay

import { useSessionReplay } from "@flagdashio/vue/replay";

useSessionReplay({ sdkKey: import.meta.env.VITE_FLAGDASH_REPLAY_KEY });

The composable starts the privacy-masked browser recorder on mount and stops it on unmount. Use a key scoped only to replays:write; capture must also be enabled for the environment in Dashboard → Session Replay.

AI releases

Create a release in Manage → AI Releases, select the environment, then set a baseline, candidate and rollout. With your initialized client, evaluate it using an environment-bound key with ai_configs:read:

const { client } = useFlagDash();
const release = await client.aiConfigRelease("support-agent", "usr_123");

The result includes key, version, config, reason, variation_key, and rollout_percentage (idiomatic field names for typed SDKs). Pass a stable user identity. Decisions are fetched afresh; verify baseline, rollout and paused behavior in development before ramping production. Your backend calls the AI provider. Ordinary evaluation leaves secret references unresolved; never put provider credentials in a configuration delivered to browsers or mobile apps. See the release guide for lifecycle and cleanup.

Remote config value format

Remote config storage and server metadata use exactly one {"value": ...} envelope. Convenience config reads return the inner application value, without recursively unwrapping application fields named value. For example, stored {"value": {"value": 7, "enabled": false}} reads as {"value": 7, "enabled": false}. Metadata methods retain the envelope.

MCP and management writes accept the envelope and automatically wrap bare objects. To store an application object whose only key is value, send {"value": {"value": 7}}. Arrays and scalar values must be inside the envelope. Existing bare stored objects are migrated, preserving secret-reference bindings. Server SDK callers previously receiving the envelope should remove their extra .value access when upgrading. Verify in a development environment first.