Introducing the Zenmanage Vue SDK
The Zenmanage Vue SDK adds a plugin, useFlag, useVariant, and FlagGate to your Vue 3 app, and renders flags on the server in Nuxt and Vite SSR without a flash of the default.
@zenmanage/vue. Install one plugin, read flags with useFlag and useVariant in any component, and render them on the server in Nuxt or Vite SSR so the browser hydrates with the same values and nothing flickers.
Adding a feature flag to a Vue app by hand is a small job that every team writes slightly differently. A client at module scope, an onMounted that fetches, a ref to hold the answer, and a moment where the page shows the wrong thing while it loads. The loading and failure paths are the ones that get skipped, and they're the ones your users see.
Server rendering makes it worse. Nuxt renders your page on the server, where onMounted never runs, so the HTML goes out with the default value. The browser then loads the real one and the page swaps. At best that's a flicker. At worst it's a hydration mismatch, because the browser's first render disagrees with the HTML it was handed. The Vue SDK is that wiring, written once, with the server case handled.
What it is
@zenmanage/vue is a thin layer over the Zenmanage JavaScript SDK, the same way the React SDK is. It doesn't reimplement evaluation, caching, or targeting. It gives you a plugin, four composables, and a FlagGate component, shaped the way Vue expects: composables return refs, and anything you'd want to change over time can itself be a ref. It needs Vue 3.4 or newer and @zenmanage/sdk 3.5.1 or newer.
Getting started
Install the package from npm. @zenmanage/sdk and vue are peer dependencies, so list them alongside it:
npm install @zenmanage/vue @zenmanage/sdk vue
Then install the plugin on your app with a client key. In the browser that's a key prefixed cli_, read from your build-time configuration:
import { createApp } from 'vue';
import { createZenmanagePlugin } from '@zenmanage/vue';
import App from './App.vue';
const app = createApp(App);
app.use(createZenmanagePlugin({ environmentToken: import.meta.env.VITE_ZENMANAGE_CLIENT_KEY }));
app.mount('#app');
The plugin loads your rules when it's created, so by the time a component asks for a flag the answer is usually already in memory. Now read a flag anywhere below it:
<script setup lang="ts">
import { useFlag } from '@zenmanage/vue';
const { value: enabled, isLoading } = useFlag('new-checkout-button', false);
</script>
<template>
<button v-if="isLoading" disabled>Loading...</button>
<button v-else>{{ enabled ? 'Checkout (New)' : 'Checkout' }}</button>
</template>
The second argument is the default, and it does two jobs. It's the value you get until the flag resolves, and again if evaluation fails. It also decides how the flag is read: pass a boolean and you get a boolean, pass a string and you get a string, pass an object or an array and you get a JSON flag. isLoading and error are refs too, so you decide what your UI does in each state. A template reads enabled, and a script reads enabled.value.
A/B testing with useVariant
A string flag can carry more than on and off. useVariant reads one as a variant name and falls back to 'control' unless you pass something else, so the baseline experience is what anyone sees if the flag can't be read:
<script setup lang="ts">
import { useVariant } from '@zenmanage/vue';
const { variant, isLoading } = useVariant('checkout-flow', 'control');
</script>
<template>
<p v-if="isLoading">Loading checkout...</p>
<OnePageCheckout v-else-if="variant === 'one-page'" />
<MultiPageCheckout v-else />
</template>
Which users land in which variant is decided in Zenmanage, through targeting rules and percentage rollouts, not in your component. Changing the split doesn't mean shipping a new build.
Two more pieces cover the rest of what you'd reach for. useConfig reads remote config values, such as a timeout or a block of copy, and useBooleanFlag is useFlag(key, false) for the common case. For a section of a page that should only exist when a flag is on, FlagGate keeps the template tidy:
<FlagGate flag-key="beta-chat">
<BetaChat />
<template #disabled><LegacyChat /></template>
<template #loading><ChatSkeleton /></template>
</FlagGate>
Keys, context, and defaults can be refs
Vue apps change over time: the user signs in, the route changes, a prop updates. A flag read shouldn't need to be torn down and rebuilt each time. Pass a ref or a getter and the SDK tracks it. This one builds the evaluation context from whoever is signed in, so every flag re-evaluates when they change:
import { computed } from 'vue';
import { Attribute, Context } from '@zenmanage/sdk';
import { createZenmanagePlugin } from '@zenmanage/vue';
const context = computed(
() => new Context('user', user.value.name, user.value.id, [new Attribute('plan', [user.value.plan])])
);
app.use(createZenmanagePlugin({ environmentToken: import.meta.env.VITE_ZENMANAGE_CLIENT_KEY, context }));
While the new values load, composables report isLoading again, so your template can show its loading state instead of the previous user's answer. The context is compared by content, so a new object that's equal to the old one doesn't restart anything. A flag key works the same way: useFlag(() => `${section.value}-limit`, 100) re-evaluates when section changes.
The context decides who a flag is evaluated for, and a percentage rollout buckets by the context's identifier, so use one that stays the same for a user across sessions.
Nuxt and server rendering, without the flash
This is the part we spent the most time on. On the server, each composable loads its flag while Vue renders, and the render waits for it, so the HTML that leaves your server already carries the real value. Then the browser has to start from the same values, or hydration complains. Here's the sequence:
- The server renders your page and evaluates every flag the page reads, using a server key.
- When the render finishes, the plugin hands you those values as plain JSON.
- You ship them to the browser, and the browser's plugin starts from them. Its first render matches the server HTML, so there's no mismatch and no flash of the default.
- The browser loads its own rules, and its live value replaces the server's when they arrive. If they never arrive, because of a blocked CDN or no network, the server's value stays.
You'll use two keys, and they never swap places. The server key (srv_) comes from a server-only environment variable, and the client key (cli_) goes to the browser. In Nuxt that maps onto runtimeConfig directly:
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// NUXT_ZENMANAGE_SERVER_KEY: a server key (srv_...). It never reaches the browser.
zenmanageServerKey: '',
public: {
// NUXT_PUBLIC_ZENMANAGE_CLIENT_KEY: a client key (cli_...).
zenmanageClientKey: '',
},
},
});
Then one plugin handles both sides. On the server it installs the plugin with the server key and, once the page has rendered, puts the flags it read into the Nuxt payload. In the browser it installs the plugin with the client key and starts from that payload:
// plugins/zenmanage.ts
import { createZenmanagePlugin, type BootstrapPayload } from '@zenmanage/vue';
export default defineNuxtPlugin(async (nuxtApp) => {
const config = useRuntimeConfig();
if (import.meta.server) {
const plugin = createZenmanagePlugin({ environmentToken: config.zenmanageServerKey });
nuxtApp.vueApp.use(plugin);
// Once the page has rendered, hand the flags it read to the browser through the Nuxt payload.
nuxtApp.hook('app:rendered', async () => {
nuxtApp.payload.zenmanage = await plugin.runtime.getBootstrapPayload();
});
return;
}
nuxtApp.vueApp.use(
createZenmanagePlugin({
environmentToken: config.public.zenmanageClientKey,
bootstrap: (nuxtApp.payload.zenmanage as BootstrapPayload | undefined) ?? null,
})
);
});
After that, useFlag and friends work in any page or component exactly as they do in a plain Vue app. There's nothing to await and no server-only branch in your components.
Not on Nuxt? Vite SSR follows the same shape. Render with renderToString, call getBootstrapPayload(), and write the result into the page with buildBootstrapScript, which escapes the payload so a flag value can't break out of the <script> tag. The browser's plugin reads that tag by itself. The Vue quickstart and the SSR guide in the repository show both.
When the API is unreachable
A flag outage shouldn't take your UI down with it. If the API can't be reached, the underlying SDK falls back to your defaults, so composables resolve to the default you passed and your components render as usual. Calling refresh() is the exception: it throws, sets error on the runtime and every composable, and calls onError, which gives you what you need to show a retry button.
Two things to know before you ship
The server key stays on the server
@zenmanage/sdk checks the key against where it's running. A srv_ key throws in a browser and a cli_ key throws in Node.js, and mobile keys (mob_) aren't valid for this package. That's deliberate: a server key in a browser bundle is a leaked secret. Read client keys from build-time configuration and keep server keys in server-only environment variables.
The bootstrap payload is public
The payload is written into the page, so anyone who views the source can read it. It holds only the flags your page actually read, with their values, and it leaves the context out by default because a context can carry personal data. If the browser needs the same user the server evaluated for, build the context again from the session, or opt in with getBootstrapPayload({ includeContext: true }) once you've checked what's in it.
What's next
@zenmanage/vue 1.0.0 is on npm now. The source is on GitHub, with runnable examples for Vite, Vite SSR, and Nuxt, and a smoke-test app we build against Vue 3.4 and the latest Vue 3 release. The Vue quickstart walks through setup end to end, and the SDK overview lists every language we support.
If something in the package gets in your way, tell us at hello@zenmanage.com or open an issue on GitHub.