@buildrflags/vue

Official Vue 3 SDK for BuildrFlags — feature flags made simple.

Installation

npm install @buildrflags/vue
# or
pnpm add @buildrflags/vue
# or
yarn add @buildrflags/vue

Quick Start

1. Install the Plugin

// main.ts
import { createApp } from 'vue';
import { BuildrFlagsPlugin } from '@buildrflags/vue';
import App from './App.vue';

const app = createApp(App);

app.use(BuildrFlagsPlugin, {
  apiKey: 'bf_production_xxx', // Your BuildrFlags API key
});

app.mount('#app');

2. Use Feature Flags in Components

<script setup lang="ts">
import { useFlag } from '@buildrflags/vue';

const { enabled, isLoading } = useFlag('new-checkout-flow');
</script>

<template>
  <LoadingSpinner v-if="isLoading" />
  <NewCheckout v-else-if="enabled" />
  <OldCheckout v-else />
</template>

Composables

useFlag(flagKey)

Get the evaluation result for a single flag.

<script setup lang="ts">
import { useFlag } from '@buildrflags/vue';

const { enabled, isLoading } = useFlag('dark-mode');
</script>

<template>
  <DarkTheme v-if="enabled" />
  <LightTheme v-else />
</template>

useFlagValue(flagKey, defaultValue?)

Simple boolean access with optional default value.

<script setup lang="ts">
import { useFlagValue } from '@buildrflags/vue';

// Returns false while loading, true once flag is fetched (if enabled)
const showBanner = useFlagValue('promo-banner', false);
</script>

<template>
  <PromoBanner v-if="showBanner" />
</template>

useFlags()

Get all flags with loading/error state and manual refresh.

<script setup lang="ts">
import { useFlags } from '@buildrflags/vue';

const { flags, isLoading, error, refresh } = useFlags();
</script>

<template>
  <div v-if="error" class="error">{{ error }}</div>
  <button @click="refresh">Refresh Flags</button>
  <pre>{{ flags }}</pre>
</template>

useFlagsEnabled(flagKeys, mode?)

Check multiple flags at once. Mode can be 'all' (default) or 'any'.

<script setup lang="ts">
import { useFlagsEnabled } from '@buildrflags/vue';

// All flags must be enabled
const canAccessPremium = useFlagsEnabled(['premium-tier', 'new-dashboard'], 'all');

// At least one flag must be enabled
const showAnyPromo = useFlagsEnabled(['black-friday', 'cyber-monday'], 'any');
</script>

<template>
  <PremiumDashboard v-if="canAccessPremium" />
  <PromoSection v-if="showAnyPromo" />
</template>

Plugin Options

interface BuildrFlagsPluginOptions {
  // Required: Your BuildrFlags API key
  apiKey: string;

  // Optional: Custom API base URL
  // Default: 'https://api.flags.buildrlab.com'
  baseUrl?: string;

  // Optional: Auto-refresh interval in milliseconds
  // Set to 0 to disable auto-refresh
  // Default: 60000 (1 minute)
  refreshInterval?: number;

  // Optional: Pre-loaded flags for SSR/SSG
  initialFlags?: Record<string, boolean>;
}

Server-Side Rendering (SSR)

For SSR with Nuxt or similar, you can pre-load flags server-side:

// Server-side: fetch flags during SSR
const response = await fetch('https://api.flags.buildrlab.com/api/evaluate/all', {
  headers: { 'X-API-Key': 'bf_production_xxx' },
});
const { flags } = await response.json();

// Convert to a simple map
const initialFlags: Record<string, boolean> = {};
for (const flag of flags) {
  initialFlags[flag.flagKey] = flag.enabled;
}

// Pass to plugin
app.use(BuildrFlagsPlugin, {
  apiKey: 'bf_production_xxx',
  initialFlags,
});

TypeScript Support

This package is written in TypeScript and includes full type definitions.

import type {
  BuildrFlagsPluginOptions,
  BuildrFlagsState,
  UseFlagResult,
  UseFlagsResult,
} from '@buildrflags/vue';

Requirements

• Vue 3.3+
• TypeScript 5.0+ (optional, but recommended)

License

MIT © BuildrLab