Getting Started

Configuration

Complete guide to configuring Nuxt Contentstack with all available options, environment settings, and best practices.

Learn how to configure Nuxt Contentstack for your specific needs. This guide covers all available options, from basic setup to advanced configurations for live preview, personalization, and multi-region deployments.

New to Contentstack? Get started with the Contentstack for Developers Academy course to learn the fundamentals of the Contentstack platform, API, and developer tools.

Basic Configuration

The minimal configuration requires three essential settings:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-contentstack'],
  
  'nuxt-contentstack': {
    apiKey: 'your_api_key',           // Required
    deliveryToken: 'your_token',      // Required  
    environment: 'production'         // Required
  }
})

Core Settings

Required Settings

Option	Type	Description
`apiKey`	`string`	Your Contentstack stack API key (starts with 'blt')
`deliveryToken`	`string`	Your delivery token (starts with 'cs')
`environment`	`string`	Target environment ('production' or 'preview')

Optional Core Settings

Option	Type	Default	Description
`region`	`string`	`'us'`	Contentstack region
`branch`	`string`	`'main'`	Content branch
`locale`	`string`	`'en-us'`	Default locale
`host`	`string`	-	Custom API host (overrides region-based URL)
`debug`	`boolean`	`false`	Enable debug logging

Regions

Contentstack supports multiple regions. Configure the correct region for your stack:

nuxt.config.ts

'nuxt-contentstack': {
  // ... other config
  region: 'us'        // or 'eu', 'au', 'azure-na', 'azure-eu', 'gcp-na', 'gcp-eu'
}

Available Regions

Region	Code	Description
North America	`us`	Default US region
Europe	`eu`	European region
Australia	`au`	Australia/Asia-Pacific
Azure North America	`azure-na`	Azure US region
Azure Europe	`azure-eu`	Azure EU region
GCP North America	`gcp-na`	Google Cloud US
GCP Europe	`gcp-eu`	Google Cloud EU

Live Preview Configuration

Enable real-time content editing with comprehensive live preview settings:

nuxt.config.ts

'nuxt-contentstack': {
  // ... core config
  livePreview: {
    enable: true,
    previewToken: 'your_preview_token',    // Required if enabled
    editableTags: true,                    // Add visual editing tags
    editButton: true,                      // Enable edit button
    mode: 'builder',                       // 'builder' or 'preview'
    ssr: false,                            // Server-side rendering for live preview
    host: ''                               // Custom Live Preview host (overrides region-based URL)
  }
}

Advanced Edit Button Configuration

Customize the edit button appearance and behavior:

nuxt.config.ts

'nuxt-contentstack': {
  // ... core config
  livePreview: {
    enable: true,
    previewToken: 'your_preview_token',
    editButton: {
      enable: true,
      position: 'top-right',               // Button position
      exclude: ['insideLivePreviewPortal'], // Where to hide button
      includeByQueryParameter: false       // Show only with ?edit=true
    }
  }
}

Edit Button Positions

Position	Description
`top`	Top center
`bottom`	Bottom center
`left`	Left center
`right`	Right center
`top-left`	Top left corner
`top-right`	Top right corner
`top-center`	Top center
`bottom-left`	Bottom left corner
`bottom-right`	Bottom right corner
`bottom-center`	Bottom center

Live Preview Modes

Mode	Description	Use Case
`builder`	Visual Builder mode	Content creation and editing
`preview`	Preview mode only	Content review and approval

Personalization Configuration

Enable Contentstack Personalize for dynamic, personalized content:

nuxt.config.ts

'nuxt-contentstack': {
  // ... core config
  personalization: {
    enable: true,
    projectUid: 'your_project_uid'        // Required if enabled
  }
}

Personalization Project UID: Find this in your Contentstack Personalize dashboard under project settings.

Environment Variables

Secure your configuration using environment variables:

.env File Setup

.env

# Core settings
NUXT_CONTENTSTACK_API_KEY=your_api_key
NUXT_CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token
NUXT_CONTENTSTACK_ENVIRONMENT=production

# Optional settings
NUXT_CONTENTSTACK_REGION=eu
NUXT_CONTENTSTACK_BRANCH=main
NUXT_CONTENTSTACK_LOCALE=en-us

# Live Preview
NUXT_CONTENTSTACK_LIVE_PREVIEW_ENABLE=true
NUXT_CONTENTSTACK_LIVE_PREVIEW_TOKEN=your_preview_token

# Personalization
NUXT_CONTENTSTACK_PERSONALIZATION_ENABLE=true
NUXT_CONTENTSTACK_PERSONALIZATION_PROJECT_UID=your_project_uid

Configuration with Environment Variables

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-contentstack'],
  
  'nuxt-contentstack': {
    apiKey: process.env.NUXT_CONTENTSTACK_API_KEY,
    deliveryToken: process.env.NUXT_CONTENTSTACK_DELIVERY_TOKEN,
    environment: process.env.NUXT_CONTENTSTACK_ENVIRONMENT,
    region: process.env.NUXT_CONTENTSTACK_REGION || 'us',
    
    livePreview: {
      enable: process.env.NUXT_CONTENTSTACK_LIVE_PREVIEW_ENABLE === 'true',
      previewToken: process.env.NUXT_CONTENTSTACK_LIVE_PREVIEW_TOKEN,
    },
    
    personalization: {
      enable: process.env.NUXT_CONTENTSTACK_PERSONALIZATION_ENABLE === 'true',
      projectUid: process.env.NUXT_CONTENTSTACK_PERSONALIZATION_PROJECT_UID,
    }
  }
})

Complete Configuration Example

Here's a full configuration example with all available options:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-contentstack', '@nuxt/image'],
  
  'nuxt-contentstack': {
    // Required core settings
    apiKey: process.env.NUXT_CONTENTSTACK_API_KEY,
    deliveryToken: process.env.NUXT_CONTENTSTACK_DELIVERY_TOKEN,
    environment: process.env.NUXT_CONTENTSTACK_ENVIRONMENT,
    
    // Optional core settings
    region: 'us',
    branch: 'main',
    locale: 'en-us',
    // host: 'custom-cdn.contentstack.io', // Optional: override API host
    
    // Live Preview configuration
    livePreview: {
      enable: true,
      previewToken: process.env.NUXT_CONTENTSTACK_PREVIEW_TOKEN,
      editableTags: true,
      editButton: {
        enable: true,
        position: 'top-right',
        exclude: ['insideLivePreviewPortal'],
        includeByQueryParameter: false
      },
      mode: 'builder',
      ssr: false,
      // host: 'custom-live-preview-host.contentstack.com' // Optional: override Live Preview host
    },
    
    // Personalization configuration
    personalization: {
      enable: true,
      projectUid: process.env.NUXT_CONTENTSTACK_PROJECT_UID
    },
    
    // Development and debugging
    debug: process.env.NODE_ENV === 'development'
  },
  
  // Optional: set Contentstack as default image provider
  // (the provider is auto-registered when @nuxt/image is installed)
  image: {
    provider: "contentstack"
  }
})

Multi-Environment Setup

Configure different settings for different environments:

nuxt.config.ts

const isDev = process.env.NODE_ENV === 'development'
const isPreview = process.env.NUXT_CONTENTSTACK_ENVIRONMENT === 'preview'

export default defineNuxtConfig({
  modules: ['nuxt-contentstack'],
  
  'nuxt-contentstack': {
    apiKey: process.env.NUXT_CONTENTSTACK_API_KEY,
    deliveryToken: process.env.NUXT_CONTENTSTACK_DELIVERY_TOKEN,
    environment: process.env.NUXT_CONTENTSTACK_ENVIRONMENT,
    
    // Enable live preview only in development or preview environment
    livePreview: {
      enable: isDev || isPreview,
      previewToken: process.env.NUXT_CONTENTSTACK_PREVIEW_TOKEN,
      editableTags: isDev || isPreview,
      editButton: isDev || isPreview
    },
    
    // Enable debug mode only in development
    debug: isDev
  }
})

Multi-Branch Support

Contentstack supports content branches for managing different versions of your content. Configure branch support:

nuxt.config.ts

'nuxt-contentstack': {
  // ... core config
  branch: 'main' // Default branch, or use 'development', 'staging', etc.
}

Dynamic Branch Selection

Switch branches dynamically based on environment or route:

nuxt.config.ts

const branch = process.env.NUXT_CONTENTSTACK_BRANCH || 'main'

export default defineNuxtConfig({
  'nuxt-contentstack': {
    // ... core config
    branch
  }
})

Branch-Specific Content

Use branches for different content versions:

<script setup>
// Content is fetched from the configured branch
const { data: page } = await useGetEntryByUrl({
  contentTypeUid: 'page',
  url: '/about'
  // Uses branch from configuration
})
</script>

Multi-Locale Support

Contentstack supports multiple locales for internationalization. Configure locale support:

Default Locale

nuxt.config.ts

'nuxt-contentstack': {
  // ... core config
  locale: 'en-us' // Default locale
}

Per-Request Locale

Override locale per composable call:

<script setup>
const route = useRoute()
const locale = computed(() => route.params.locale || 'en-us')

// Fetch content in specific locale
const { data: page } = await useGetEntryByUrl({
  contentTypeUid: 'page',
  url: '/about',
  locale: locale.value
})
</script>

Locale Switching

Implement locale switching:

composables/useLocale.ts

export const useLocale = () => {
  const route = useRoute()
  const router = useRouter()
  
  const currentLocale = computed(() => {
    return route.params.locale as string || 'en-us'
  })
  
  const switchLocale = (newLocale: string) => {
    const path = route.path.replace(`/${currentLocale.value}`, `/${newLocale}`)
    router.push(path)
  }
  
  return {
    currentLocale,
    switchLocale
  }
}

Locale Fallback

Implement locale fallback strategies:

<script setup>
const route = useRoute()
const locale = computed(() => route.params.locale || 'en-us')
const fallbackLocale = 'en-us'

// Try primary locale first
const { data: page } = await useGetEntryByUrl({
  contentTypeUid: 'page',
  url: '/about',
  locale: locale.value
})

// Fallback to default locale if not found
if (!page.value && locale.value !== fallbackLocale) {
  const { data: fallbackPage } = await useGetEntryByUrl({
    contentTypeUid: 'page',
    url: '/about',
    locale: fallbackLocale
  })
  // Use fallbackPage if available
}
</script>

Multi-Locale Routing

Set up routes for multiple locales:

pages/[...locale]/[...slug].vue

<script setup>
const route = useRoute()
const locale = computed(() => {
  const segments = route.params.locale as string[]
  return segments?.[0] || 'en-us'
})
const slug = computed(() => {
  const segments = route.params.slug as string[]
  return segments ? `/${segments.join('/')}` : '/'
})

const { data: page } = await useGetEntryByUrl({
  contentTypeUid: 'page',
  url: slug.value,
  locale: locale.value
})

if (!page.value) {
  throw createError({
    statusCode: 404,
    statusMessage: 'Page Not Found'
  })
}
</script>

<template>
  <main v-if="page">
    <h1>{{ page.title }}</h1>
    <div v-html="page.content"></div>
  </main>
</template>

Locale Detection

Auto-detect locale from browser or headers:

composables/useLocaleDetection.ts

export const useLocaleDetection = () => {
  const route = useRoute()
  
  const detectLocale = (): string => {
    // 1. Check route parameter
    if (route.params.locale) {
      return route.params.locale as string
    }
    
    // 2. Check browser language (client-side)
    if (import.meta.client && navigator.language) {
      const browserLang = navigator.language.toLowerCase()
      // Map browser language to supported locales
      const supportedLocales = ['en-us', 'es-es', 'fr-fr', 'de-de']
      const match = supportedLocales.find(locale => 
        locale.startsWith(browserLang.split('-')[0])
      )
      if (match) return match
    }
    
    // 3. Check Accept-Language header (server-side)
    if (import.meta.server) {
      const headers = useRequestHeaders()
      const acceptLanguage = headers['accept-language']
      // Parse and match supported locales
    }
    
    // 4. Default fallback
    return 'en-us'
  }
  
  return {
    detectedLocale: computed(detectLocale)
  }
}

Debug Mode

Enable debug mode to troubleshoot configuration issues:

nuxt.config.ts

'nuxt-contentstack': {
  // ... other config
  debug: true
}

Debug mode outputs:

Complete configuration object
SDK initialization details
API request and response logs
Cache operation details

Next Steps

Now that you have Nuxt Contentstack properly configured:

Components & Blocks

Learn about ContentstackModularBlocks and building dynamic layouts.

Image Optimization

Optimize images with Contentstack's Image Delivery API integration.

Performance Optimization

Optimize your application for speed and efficiency.

Edit this pageorReport an issue

Quick Start

Get started quickly with Nuxt Contentstack using these practical examples covering basic usage, live preview, and modular blocks.

Composables

Learn how to use Nuxt Contentstack composables to fetch entries, assets, and content with type safety, caching, and live preview support.