Nuxt Contentstack Nuxt Contentstack
Getting Started

Installation

Learn how to install and set up Nuxt Contentstack in your project with step-by-step instructions and configuration options.

Get up and running with Nuxt Contentstack in just a few minutes. This guide covers installation, basic configuration, and verification steps.

Requirements

This module requires:

  • Nuxt 3.20.1 or higher (including Nuxt 4.x)
  • @nuxt/image ^2.0.0 (only required for image provider functionality)

Prerequisites

Before installing Nuxt Contentstack, ensure you have:

  • Nuxt 3.20.1+ or Nuxt 4
  • A Contentstack account with a configured stack
  • Your Contentstack API credentials (API Key, Delivery Token, Environment)
Nuxt Version: This module requires Nuxt 3.20.1 or higher for optimal compatibility. For the best experience, we recommend using Nuxt 4.
@nuxt/image: The module can run without @nuxt/image, but it's required if you want to use the Contentstack image provider for image optimization features. Install it with: npm install @nuxt/image@^2.0.0 when you need image optimization.

Quick Installation

The fastest way to add Nuxt Contentstack to your project is using the Nuxt CLI:

npx nuxi module add nuxt-contentstack

This command will:

  • Install the nuxt-contentstack package
  • Add the module to your nuxt.config.ts
  • Set up basic configuration structure

Manual Installation

If you prefer manual installation or need more control:

1. Install the Package

npm install nuxt-contentstack

2. Add to Nuxt Configuration

Add the module to your nuxt.config.ts:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-contentstack']
})

Basic Configuration

After installation, configure the module with your Contentstack credentials:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-contentstack'],
  
  'nuxt-contentstack': {
    // Required: Core Contentstack settings
    apiKey: 'your_contentstack_api_key',
    deliveryToken: 'your_delivery_token',
    environment: 'production',
    
    // Optional: yet important
    region: 'eu',       // 'us' | 'eu' | 'au' | 'azure-na' | 'azure-eu' | 'gcp-na' | 'gcp-eu'
    branch: 'main',     // Content branch (main is the default)
    locale: 'en-us',    // Default locale (en-us is the default)
    // host: '',        // Custom API host (overrides region-based URL)
    debug: false        // Enable debug logging
  }
})
API Credentials: You can find your API Key, Delivery Token, and Environment in your Contentstack stack settings under "Settings" → "Tokens".

Environment Variables

For security, it's recommended to use environment variables for sensitive credentials:

.env
NUXT_CONTENTSTACK_API_KEY=your_api_key_here
NUXT_CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token_here
NUXT_CONTENTSTACK_ENVIRONMENT=production

Then reference them in your configuration:

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,
  }
})

@nuxt/image Configuration (Optional)

If you want to use Contentstack's image optimization features, install and configure @nuxt/image:

npm install @nuxt/image@^2.0.0
nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    'nuxt-contentstack',
    '@nuxt/image' // Only needed for image optimization
  ]
})
Auto-registration: When @nuxt/image is installed, the module automatically registers the Contentstack image provider. No manual provider configuration is needed. Just use provider="contentstack" on your <NuxtImg> and <NuxtPicture> components.

If you want to set Contentstack as the default image provider (so you don't need provider="contentstack" on every component), add this:

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    provider: "contentstack"
  }
})


## Verification

After installation and configuration, verify everything is working:

### 1. Check Module Loading

Start your development server:

```bash
npm run dev

Look for Contentstack initialization messages in the console:

✅ Contentstack region: your region
✅ Contentstack branch: your branch

2. Test Basic Query

Create a simple page to test the connection:

pages/test.vue
<script setup>
// Test basic connection
const { data: entries } = await useGetEntries({
  contentTypeUid: 'your_content_type_uid', // page
  limit: 1
})
</script>

<template>
  <div>
    <h1>Contentstack Test</h1>
    <pre>{{ entries }}</pre>
  </div>
</template>

3. Debug Mode

Enable debug mode for detailed logging:

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

This will output detailed configuration and request information to help diagnose issues.

Next Steps

Now that you have Nuxt Contentstack installed and configured:

Quick Start

Get started quickly with practical examples you can copy and use right away.

Configuration Guide

Learn about all available configuration options and advanced settings.

Composables Reference

Explore all available composables for fetching content.

Live Preview

Enable real-time content editing for your content team.

Happy coding with Nuxt Contentstack! 🚀

Introduction

Learn about Nuxt Contentstack, a powerful integration module that brings together Contentstack CMS and Nuxt framework for modern content-driven applications.

Quick Start

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