@flagdeck/vue/README.md

Vue integration for Flagdeck feature flags

# Flagdeck Vue SDK

## Overview

The Flagdeck Vue SDK provides seamless integration of the Flagdeck feature flag system with Vue 3 applications. This SDK enables you to implement feature flags, A/B testing, and targeted rollouts in your Vue apps with minimal effort.

## Installation

```bash
npm install @flagdeck/vue
# or
yarn add @flagdeck/vue
# Using pnpm
pnpm add @flagdeck/vue
```

## Quick Start

Initialize the Flagdeck plugin in your Vue app:

```typescript
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { createFlagdeckPlugin } from '@flagdeck/vue';

const app = createApp(App);

app.use(
  createFlagdeckPlugin({
    clientOptions: {
      apiKey: 'YOUR_API_KEY',
      debug: true,
      realTimeUpdates: true,
    },
    context: {                // Targeting context for flag evaluation
      userId: 'user-123',
      attributes: {
        country: 'US',
        plan: 'premium'
      }
    }
  })
);

app.mount('#app');
```

Then use one of our composables or components to check feature flags:

```vue
<template>
  <div>
    <div v-if="isLoading">Loading...</div>
    <div v-else>
      <div v-if="isEnabled">
        <p>New feature is enabled!</p>
      </div>
      <div v-else>
        <p>New feature is disabled.</p>
      </div>
    </div>
  </div>
</template>

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

  export default defineComponent({
    setup() {
      const { isEnabled, isLoading } = useFlag('new-feature');

      return {
        isEnabled,
        isLoading
      };
    }
  });
</script>
```

## Core Components

### `<FeatureFlag />`

Component for conditional rendering based on flag state:

```vue
<template>
  <FeatureFlag flag-key="new-feature">
    <template #default>
      <p>Feature enabled!</p>
    </template>
    <template #fallback>
      <p>Feature disabled</p>
    </template>
    <template #loading>
      <p>Loading...</p>
    </template>
  </FeatureFlag>
</template>

<script>
  import { FeatureFlag } from '@flagdeck/vue';

  export default {
    components: {
      FeatureFlag
    }
  };
</script>
```

### `<WithFeature />`

Scoped slot component for more flexible control:

```vue
<template>
  <WithFeature flag-key="premium-dashboard">
    <template #default="{ isEnabled, isLoading }">
      <div v-if="isLoading">Loading...</div>
      <PremiumDashboard v-else-if="isEnabled" />
      <UpgradeBanner v-else />
    </template>
  </WithFeature>
</template>

<script>
  import { WithFeature } from '@flagdeck/vue';

  export default {
    components: {
      WithFeature
    }
  };
</script>
```

### `<FlagValue />`

Component to access and render specific flag values:

```vue
<template>
  <FlagValue flag-key="theme-color" :default-value="'blue'">
    <template #default="{ value, isLoading }">
      <div v-if="isLoading">Loading...</div>
      <div v-else :style="{ backgroundColor: value }">
        Theme color: {{ value }}
      </div>
    </template>
  </FlagValue>
</template>

<script>
  import { FlagValue } from '@flagdeck/vue';

  export default {
    components: {
      FlagValue
    }
  };
</script>
```

## Composables

### `useFlag(flagKey, defaultValue)`

Composable to check if a feature flag is enabled:

```typescript
const { isEnabled, isLoading, error } = useFlag('new-feature', false);
```

### `useFlagValue(flagKey, defaultValue)`

Composable to get the specific value of a feature flag:

```typescript
const { value, isLoading, error } = useFlagValue('theme-color', 'blue');
```

### `useFlags(flagKeys, defaultValue)`

Composable to check multiple flags at once:

```typescript
const { values, isLoading, errors } = useFlags(['feature-a', 'feature-b'], false);
// values.value = { 'feature-a': true, 'feature-b': false }
```

### `useFlagdeck()`

Composable to access the Flagdeck client instance and context:

```typescript
const { client, isReady, error, context, setContext } = useFlagdeck();

// Update the context at runtime
setContext({
  userId: 'user-456',
  attributes: {
    plan: 'enterprise'
  }
});
```

## Real-time Updates

The SDK supports real-time flag updates using Server-Sent Events (SSE). Enable real-time updates in the options to automatically update your UI when flag values change:

```typescript
app.use(
  createFlagdeckPlugin({
    clientOptions: {
      apiKey: 'YOUR_API_KEY',
      realTimeUpdates: true,  // Enable real-time updates
    },
    context: {
      userId: 'user-123',
      attributes: { plan: 'premium' }
    }
  })
);
```

## Error Handling

All composables and components provide error information to help with debugging and fallback scenarios.

## Complete API Reference

For detailed API documentation, advanced usage examples, and all available options, please visit the [official Flagdeck Vue SDK documentation](https://flagdeck.com/docs/sdks/vue).

The API reference includes:
- Complete `clientOptions` configuration for `createFlagdeckPlugin`
- All available context attributes for targeting
- Advanced flag evaluation strategies
- Component props and slot API details
- TypeScript interfaces and type definitions
- Vue 3 composables best practices

## License

MIT