Skip to main content

Nuxt SDK

Requirements

Use Nuxt 3 or Nuxt 4 and Node.js 18+. The published module peer range is nuxt ^3.0.0 || ^4.0.0.

Start with the Nuxt SDK sample. Read its README, then work through the home, declarative gates, programmatic API, request-scoped identity, Order context, and filter examples in that order. Use the Samples catalog to find the other runnable SDK examples.

Use Toggly's feature flags in Nuxt 3 and Nuxt 4 applications with full SSR/SSG support, auto-imported composables, components, and server utilities.

Grab the printable Nuxt cheat sheet (download PDF) — Nitro server handlers, Vue composables, directives, middleware.

The module connects the core, Nitro server integration and browser client.

Architecture​

The Nuxt SDK is modular with 4 packages:

PackageDescription
@ops-ai/nuxt-togglyMain Nuxt module (recommended)
@ops-ai/nuxt-toggly-coreShared types and utilities (zero dependencies)
@ops-ai/nuxt-toggly-serverServer-side Nitro utilities
@ops-ai/nuxt-toggly-clientVue 3 composables, components, directives

Benefits​

  • ✅ Server-only routes don't bundle Vue
  • ✅ Client code doesn't bundle server utilities
  • ✅ Full TypeScript support
  • ✅ Auto-imported composables
  • ✅ Global components and directives
  • ✅ SSR/SSG support with proper hydration

Installation​

npm install @ops-ai/nuxt-toggly

Or with other package managers:

yarn add @ops-ai/nuxt-toggly
pnpm add @ops-ai/nuxt-toggly

Quick Start​

1. Configure Module​

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

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

2. Use in Components​

pages/dashboard.vue
<script setup>
// Composables are auto-imported!
const { isEnabled } = useFeatureFlag('new-dashboard')
</script>

<template>
  <NewDashboard v-if="isEnabled" />
  <OldDashboard v-else />
</template>

3. Use Feature Component​

<template>
  <Feature feature-key="beta-feature">
    <BetaContent />
  </Feature>
  <Feature feature-key="beta-feature" negate>
    <StableContent />
  </Feature>
</template>

Features​

Client-Side​

  • Composables: useToggly(), useFeatureFlag(), useFeatureGate(), useFeatureOff(), useVariant()
  • Components: <Feature> (negate for the off path)
  • Directives: v-feature, v-feature-show, v-feature-class
  • Identity: Persist user identity for targeting
  • Variants: enableVariants + useVariant() / getVariant() / getVariantValue()
  • Offline: Optional localStorage persistence

Server-Side​

  • Middleware: defineFeatureMiddleware() for route protection
  • Handlers: defineFeatureHandler() for protected API routes
  • Utilities: isEventFeatureOn(), useEventToggly(), getServerVariant(), getServerVariantValue()
  • Caching: Automatic server-side caching

Next Steps​