Configuration

Configure the Toggly Nuxt module in your nuxt.config.ts.

Basic Configuration

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@ops-ai/nuxt-toggly'],

  toggly: {
    appKey: process.env.TOGGLY_APP_KEY,
    environment: 'Production',
  },
})

All Options

nuxt.config.ts

export default defineNuxtConfig({
  toggly: {
    // === Connection Settings ===

    // Your Toggly application key (required for Toggly.io)
    appKey: 'your-app-key',

    // Environment name
    environment: 'Production', // default

    // API base URL
    baseUri: 'https://definitions.toggly.io', // default

    // === User Identity ===

    // User identity for targeting and rollouts
    identity: undefined,

    // Persist identity to localStorage
    persistIdentity: true, // default

    // === Feature Defaults ===

    // Default values when API is unavailable
    featureDefaults: {
      'my-feature': true,
      'beta-feature': false,
    },

    // === Behavior ===

    // Show content while evaluating features
    showFeatureDuringEvaluation: false, // default

    // Auto-refresh interval in milliseconds (0 to disable HTTP polling)
    refreshInterval: 180000, // default: 3 minutes (client); server uses 0

    // WebSocket live updates (default: on when unset). Set false to disable.
    // Server SDK injects the `ws` package; Edge runtimes skip long-lived sockets.
    enableLiveUpdates: true,

    // === Server Settings ===

    // Enable server-side rendering support
    ssr: true, // default

    // Cache features on server
    serverCache: true, // default

    // Server cache TTL in milliseconds
    serverCacheTtl: 60000, // default: 1 minute

    // === Client Settings ===

    // Persist features to localStorage for offline support
    persistFeatures: false, // default

    // === Module Features ===

    // Auto-import composables (useFeatureFlag, etc.)
    autoImport: true, // default

    // Register global components (Feature)
    globalComponents: true, // default

    // Register global directives (v-feature, v-feature-show, v-feature-class)
    globalDirectives: true, // default

    // === Development ===

    // Enable debug logging
    debug: false, // default

    // === Extensibility ===

    // Custom hooks for analytics, logging, etc.
    hooks: [],
  },
})

Environment-Based Configuration

nuxt.config.ts

export default defineNuxtConfig({
  toggly: {
    appKey: process.env.TOGGLY_APP_KEY,
    environment: process.env.NODE_ENV === 'production'
      ? 'Production'
      : 'Staging',
    debug: process.env.NODE_ENV !== 'production',
  },
})

Using Environment Variables

.env

TOGGLY_APP_KEY=your-app-key
TOGGLY_ENVIRONMENT=Production

nuxt.config.ts

export default defineNuxtConfig({
  toggly: {
    appKey: process.env.TOGGLY_APP_KEY,
    environment: process.env.TOGGLY_ENVIRONMENT || 'Production',
  },
})

Offline Mode

Use feature flags without connecting to Toggly.io:

nuxt.config.ts

export default defineNuxtConfig({
  toggly: {
    // No appKey needed
    featureDefaults: {
      'new-dashboard': true,
      'beta-feature': false,
      'dark-mode': true,
    },
  },
})

Runtime Configuration

Access configuration at runtime:

<script setup>
const config = useRuntimeConfig()
const togglyConfig = config.public.toggly

console.log('Environment:', togglyConfig.environment)
</script>

Error reporting and refresh behavior

Pass onError in nuxt.config.ts to observe fetch, cache, parse, WebSocket, and refresh failures on both client and server. Define the handler inline in nuxt.config.ts so the module can wire it into the generated client and Nitro plugins:

nuxt.config.ts

export default defineNuxtConfig({
  toggly: {
    appKey: 'your-app-key',
    environment: 'Production',
    onError: (message, error) => {
      monitoring.captureException(error, {
        tags: { source: 'toggly' },
        extra: { message },
      })
    },
  },
})

When you create a Toggly client directly, pass the same callback to createToggly():

import { createToggly } from '@ops-ai/nuxt-toggly-client'

const toggly = createToggly({
  appKey: 'your-app-key',
  environment: 'Production',
  onError: (message, error) => {
    monitoring.captureException(error, {
      tags: { source: 'toggly' },
      extra: { message },
    })
  },
})

For module-based setup, read the current error state through useToggly():

<script setup lang="ts">
const { error } = useToggly()
</script>

<template>
  <ErrorBanner v-if="error" :error="error" />
</template>

After one successful load, refresh failures preserve the last-known-good flags instead of replacing rendered content with defaults or empty flags. Nuxt composables, components, and v-feature directives subscribe to feature refreshes, so interval and WebSocket updates can re-render UI automatically.

For the shared reliability contract, see Reliability and Error Handling.

Groups, claims, and signed definitions

@ops-ai/nuxt-toggly-core accepts init-time groups, claims, and verifySignatures on TogglyConfig. Runtime updates support identity only via setIdentity — there is no setContext({ groups, claims }).

import { createToggly } from '@ops-ai/nuxt-toggly-client'

const toggly = createToggly({
  appKey: 'your-app-key',
  environment: 'Production',
  identity: 'user-123',
  groups: ['beta', 'enterprise'],
  claims: { role: 'admin', plan: 'premium' },
  enableLiveUpdates: true, // default
  verifySignatures: true,
})

The Nuxt module forwards initial identity, groups, and claims to its clients. Use the direct client configuration above for options such as verifySignatures that the module does not forward.

See Evaluated-signed and WebSocket sync.

Initial context through the Nuxt module

Configure application-wide targeting defaults in nuxt.config:

export default defineNuxtConfig({
  modules: ['@ops-ai/nuxt-toggly'],
  toggly: {
    appKey: 'your-app-key',
    groups: ['beta'], // Public application defaults, not request authentication.
    claims: { plan: 'pro' }, // String rule attributes.
  },
})

Supply known context before client initialization. Module configuration is application-wide and public; obtain per-user server context in the request instead of assigning one user's identity globally. Empty collections add no memberships/claims. The client's persisted cache does not provide context isolation; do not rely on it to separate sensitive decisions between users.

Usage & metrics

Optional usage statistics and business metrics on the Nitro server (gRPC on Node; HTTPS on Nitro edge). Defaults on when appKey is set (enableUsageTracking, enableMetrics, metricsBaseUrl, flush intervals): Usage & metrics.

See also

• Usage & metrics
• WebSocket sync and definitions revision
• Evaluated-signed responses
• Reliability and Error Handling

Custom Hooks

Add custom hooks for analytics or logging:

nuxt.config.ts

import type { Hook } from '@ops-ai/nuxt-toggly'

const analyticsHook: Hook = {
  getMetadata: () => ({ name: 'analytics' }),

  async afterEvaluation(flagKey, data, result) {
    // Track feature evaluation
    console.log(`Feature ${flagKey}: ${result}`)
  },
}

export default defineNuxtConfig({
  toggly: {
    appKey: 'your-key',
    hooks: [analyticsHook],
  },
})

Disabling Features

Disable Auto-Imports

export default defineNuxtConfig({
  toggly: {
    autoImport: false, // Manually import composables
  },
})

Disable Components

export default defineNuxtConfig({
  toggly: {
    globalComponents: false, // Don't register Feature components globally
  },
})

Disable Directives

export default defineNuxtConfig({
  toggly: {
    globalDirectives: false, // Don't register v-feature directives
  },
})

Disable SSR

export default defineNuxtConfig({
  toggly: {
    ssr: false, // Client-only mode
  },
})