Vuev1.2.1Frontend

Vue SDK

Add feature flags to your Vue application with a plugin and composables. Wraps @rollgate/sdk-browser for real-time updates, SSE streaming, and TypeScript support.

Installation

npm install @rollgate/sdk-vue
# or
yarn add @rollgate/sdk-vue
# or
pnpm add @rollgate/sdk-vue

Quick Start

1. Install the Plugin

main.ts

import { createApp } from 'vue';
import { rollgatePlugin } from '@rollgate/sdk-vue';
import App from './App.vue';

const app = createApp(App);

app.use(rollgatePlugin, {
  apiKey: 'rg_client_...',
  baseUrl: 'https://api.rollgate.io',
});

app.mount('#app');

2. Use the Composable

Access flags in your components with useFlag:

components/Feature.vue

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

const isEnabled = useFlag('my-feature', false);
</script>

<template>
  <NewFeature v-if="isEnabled" />
</template>

Plugin Options

Option	Type	Default	Description
apiKey	string	required	Your Rollgate client API key
baseUrl	string	'https://api.rollgate.io'	Rollgate API base URL
refreshInterval	number	30000	Polling interval in milliseconds
enableStreaming	boolean	false	Use SSE for real-time updates (opt-in)
user	UserContext	undefined	Initial user context for targeting

Composables

useFlag

Returns a reactive ref for a single flag value. Updates automatically when flag values change.

import { useFlag } from '@rollgate/sdk-vue';

// Boolean flag
const isEnabled = useFlag('flag-key', false);

// Use in template: {{ isEnabled }}

Option	Type	Default	Description
flagKey	string	required	The flag key to check
defaultValue	boolean	false	Value to return if flag not found

useFlags

Get all flags as a reactive object, along with loading and error state:

import { useFlags } from '@rollgate/sdk-vue';

const { flags, isLoading, error } = useFlags();

// Access individual flags
// flags['new-feature']

useRollgate

Access the full Rollgate context for advanced use cases like identifying users and forcing refreshes:

import { useRollgate } from '@rollgate/sdk-vue';

const {
  flags,
  isLoading,
  error,
  identify,  // Set user context
  refresh,   // Force refresh flags
} = useRollgate();

// Identify user after login
await identify({
  id: 'user-123',
  email: '[email protected]',
  attributes: { plan: 'pro' }
});

User Targeting

Pass user information to enable targeting rules, percentage rollout, and target user lists. The SDK sends this context to the server where rules are evaluated securely.

User Context Structure

interface UserContext {
  id: string;           // Required for percentage rollout
  email?: string;       // For email-based targeting
  attributes?: {        // Any custom attributes for targeting rules
    plan?: string;      // e.g., "free", "pro", "growth"
    country?: string;   // e.g., "IT", "US", "DE"
    company?: string;   // e.g., "Acme Inc"
    app_version?: string; // e.g., "2.1.0" (for semver comparisons)
    [key: string]: string | number | boolean;
  };
}

Setting User Context

Option 1: In plugin options (known user at startup)

app.use(rollgatePlugin, {
  apiKey: 'rg_client_...',
  baseUrl: 'https://api.rollgate.io',
  user: {
    id: 'user-123',
    email: '[email protected]',
    attributes: {
      plan: 'pro',
      country: 'IT',
      company: 'Acme Inc',
      app_version: '2.1.0'
    }
  }
});

Option 2: After authentication (dynamic)

<script setup lang="ts">
import { watch } from 'vue';
import { useRollgate } from '@rollgate/sdk-vue';
import { useAuth } from './composables/auth';

const { identify } = useRollgate();
const { user } = useAuth();

watch(user, async (newUser) => {
  if (newUser) {
    await identify({
      id: newUser.id,
      email: newUser.email,
      attributes: {
        plan: newUser.subscription.plan,
        country: newUser.profile.country,
        company: newUser.organization?.name,
        app_version: APP_VERSION
      }
    });
  }
});
</script>

Targeting Rules Example

With the user context above, your targeting rules can match on any attribute:

Example: Pro Italian Users on v2+

Dashboard rule configuration:

Rule: "Pro Italian Users on v2+"
Conditions (all must match):
  - plan IN "pro,growth"
  - country EQUALS "IT"
  - app_version SEMVER_GTE "2.0.0"

// This user will match:
{
  id: "user-123",
  attributes: {
    plan: "pro",      // matches [pro, growth]
    country: "IT",     // equals IT
    app_version: "2.1.0" // >= 2.0.0
  }
}

Security: Rules are evaluated server-side. Users cannot see or manipulate the targeting logic - they only receive the final boolean result.

TypeScript

The SDK is fully typed. Define your flag keys for type safety:

// types/flags.ts
export type FlagKey =
  | 'new-checkout'
  | 'dark-mode'
  | 'beta-features';

// Usage in component
import { useFlag } from '@rollgate/sdk-vue';
import type { FlagKey } from '@/types/flags';

const isEnabled = useFlag<FlagKey>('new-checkout');

Full Example

App.vue

<script setup lang="ts">
import { useFlag, useRollgate } from '@rollgate/sdk-vue';

const showNewDashboard = useFlag('new-dashboard', false);
const showBetaBanner = useFlag('beta-banner', false);
const { isLoading, error } = useRollgate();
</script>

<template>
  <div v-if="isLoading" class="loading">Loading flags...</div>
  <div v-else-if="error" class="error">{{ error.message }}</div>
  <template v-else>
    <BetaBanner v-if="showBetaBanner" />
    <NewDashboard v-if="showNewDashboard" />
    <LegacyDashboard v-else />
  </template>
</template>

React SDK

Feature flags with hooks and context providers

Node.js SDK

Server-side feature flags with circuit breaker