Install

npm install @arlioz/flagship-nuxt @arlioz/flagship

@arlioz/flagship, vue, and nuxt are peer dependencies.

Quick Start

1. Create a Nuxt plugin

// plugins/flagship.ts
import { createFlagShipContext, startClientPolling } from '@arlioz/flagship-nuxt'
import { fetchFlags } from '@arlioz/flagship-nuxt/server'

export default defineNuxtPlugin(async (nuxtApp) => {
  const initialFlags = import.meta.server
    ? await fetchFlags({
        apiKey: useRuntimeConfig().flagshipApiKey,
        baseUrl: useRuntimeConfig().flagshipApiUrl,
      })
    : undefined

  const isServer = import.meta.server
  const flagState = useState('flagship-flags', () => initialFlags ?? {})

  const context = createFlagShipContext(
    {
      apiKey: useRuntimeConfig().public.flagshipApiKey,
      initialFlags: flagState.value,
    },
    isServer,
  )

  if (!isServer) {
    const cleanup = startClientPolling(
      context,
      30000,
      (flags) => {
        flagState.value = flags
      },
      () => {},
    )
    nuxtApp.hook('app:unmounted', cleanup)
  }

  return { provide: { flagship: context } }
})

2. Use flags in components

<script setup>
import { getFlag } from '@arlioz/flagship-nuxt'

const { $flagship } = useNuxtApp()
const darkMode = getFlag($flagship, 'dark-mode', false)
</script>

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

3. Use flags in server routes

// server/api/feature.ts
import { fetchFlag } from '@arlioz/flagship-nuxt/server'

export default defineEventHandler(async () => {
  const enabled = await fetchFlag(
    { apiKey: useRuntimeConfig().flagshipApiKey },
    'new-checkout',
    false,
  )
  return { enabled }
})

Two Entry Points

| Import | Use in | Description | | ------------------------------ | ------------------------- | ----------------------------- | | @arlioz/flagship-nuxt | Nuxt plugins, components | Context, composables | | @arlioz/flagship-nuxt/server | Server routes, middleware | fetchFlags(), fetchFlag() |

API — Client

| Function | Return | Description | | ------------------------------------------------------ | --------------------- | -------------------------------- | | createFlagShipContext(options, isServer) | FlagShipNuxtContext | Create SSR-aware context | | startClientPolling(ctx, interval, onUpdate, onReady) | () => void | Start polling, returns cleanup | | getFlag(ctx, key, default?) | T | Single flag value | | getFlags(ctx) | Record<string, any> | All flags | | isLoading(ctx) | boolean | Loading state | | getClient(ctx) | FlagShip \| null | Client instance (null on server) |

API — Server

| Function | Return | Description | | ----------------------------------- | ------------------------------ | -------------------------------- | | fetchFlags(options) | Promise<Record<string, any>> | Fetch all flags (auto-cleanup) | | fetchFlag(options, key, default?) | Promise<T> | Fetch single flag (auto-cleanup) | | FlagShipServer | class | Long-lived server client |

SSR Benefits

• No hydration mismatch — flags fetched server-side, hydrated via useState
• No flash of default content — correct on first render
• Client-side polling — flags update automatically after hydration

Compatibility

• Nuxt >= 3.0.0
• Vue >= 3.3.0

License

MIT — Arlioz