Nuxt Contentstack

Contentstack integration for Nuxt.

• ✨  Release Notes
• 🏀 Online playground
• 📖 Documentation

Notice: This is an OSS project by @timbenniks and not an officially maintained package by the Contentstack team. Support requests can come through Github issues and via direct channels to @timbenniks.

Requirements

This module requires:

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

Make sure to install these dependencies in your project:

npm install nuxt@^3.20.1 @nuxt/image@^2.0.0
# or
pnpm add nuxt@^3.20.1 @nuxt/image@^2.0.0
# or
yarn add nuxt@^3.20.1 @nuxt/image@^2.0.0

Features

• Complete set of Vue composables (entries, assets, by URL)
• Advanced filtering, pagination, and sorting
• Live Preview & Visual Builder support
• Personalization support with server-side middleware
• Image transformations with useImageTransform composable
• @nuxt/image integration with automatic optimization
• TypeScript support with full type safety
• Exposed SDKs: Delivery SDK, Live Preview Utils SDK, Personalize SDK

Quick Setup

npx nuxi module add nuxt-contentstack

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["nuxt-contentstack"],

  "nuxt-contentstack": {
    // Required
    apiKey: "your_contentstack_api_key",
    deliveryToken: "your_delivery_token",
    environment: "your_environment",

    // Optional
    region: "eu", // 'us' | 'eu' | 'au' | 'azure-na' | 'azure-eu' | 'gcp-na' | 'gcp-eu'
    branch: "main",
    locale: "en-us",

    // Live Preview
    livePreview: {
      enable: true,
      previewToken: "your_preview_token",
      editableTags: true,
      editButton: true, // or object with enable, position, exclude, includeByQueryParameter
      mode: "builder", // 'builder' | 'preview'
      ssr: false,
    },

    // Personalization
    personalization: {
      enable: true,
      projectUid: "your_project_uid",
    },

    debug: true,
  },
});

Configuration

Core Settings

Option	Type	Required	Default	Description
apiKey	string	Yes	-	Contentstack stack API key (starts with “blt”)
deliveryToken	string	Yes	-	Delivery token (starts with “cs”)
environment	string	Yes	-	Target environment (‘preview’ | ‘production’)
region	string	No	'us'	Contentstack region
branch	string	No	'main'	Content branch
locale	string	No	'en-us'	Default locale
debug	boolean	No	false	Enable debug logging

Live Preview

Option	Type	Default	Description
enable	boolean	false	Enable live preview
previewToken	string	-	Preview token (required if enabled)
editableTags	boolean	false	Add editable tags for visual building
editButton	boolean | object	false	Enable/edit button config
mode	'builder' | 'preview'	'builder'	Live preview mode
ssr	boolean	false	Enable SSR mode (experimental)

Edit button object:

editButton: {
  enable: boolean
  position?: 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'
  exclude?: ('insideLivePreviewPortal' | 'outsideLivePreviewPortal')[]
  includeByQueryParameter?: boolean
}

Personalization

Option	Type	Required	Description
enable	boolean	Yes	Enable personalization
projectUid	string	Yes	Personalization project UID

Provides

Access via useNuxtApp().$contentstack:

const {
  stack, // Delivery SDK Stack instance
  ContentstackLivePreview, // Live Preview Utils SDK
  Personalize, // Personalize SDK
  livePreviewEnabled, // boolean
  editableTags, // boolean
  variantAlias, // Variant manifest for personalization
  VB_EmptyBlockParentClass, // Visual Builder empty block class
} = useNuxtApp().$contentstack;

Personalization SDK Usage

const { Personalize } = useNuxtApp().$contentstack;

// Set user attributes
await Personalize.set({ age: 20 });

// Trigger impression
await Personalize.triggerImpression(experienceShortId);

// Trigger conversion event
await Personalize.triggerEvent("eventKey");

Composables

All composables support live preview updates, personalization variants, and Nuxt’s caching system.

useGetEntryByUrl

Fetch entry by URL field.

const { data, status, refresh } = await useGetEntryByUrl<Page>({
  contentTypeUid: "page",
  url: "/about",
  referenceFieldPath: ["author", "category"],
  jsonRtePath: ["rich_text_field"],
  locale: "en-us",
  replaceHtmlCslp: true,
});

useGetEntry

Fetch single entry by UID.

const { data } = await useGetEntry<Article>({
  contentTypeUid: "article",
  entryUid: "your_entry_uid",
  referenceFieldPath: ["author"],
  jsonRtePath: ["content"],
  locale: "en-us",
});

useGetEntries

Fetch multiple entries with filtering, pagination, and sorting.

const { data } = await useGetEntries<Article>({
  contentTypeUid: "article",
  referenceFieldPath: ["author"],
  locale: "en-us",
  limit: 10,
  skip: 0,
  orderBy: "created_at",
  includeCount: true,
  where: {
    status: "published",
    view_count: { $gt: 1000 },
    created_at: { $gte: "2024-01-01", $lt: "2024-12-31" },
    featured_image: { $exists: true },
    title: { $regex: "nuxt.*contentstack" },
    tags: ["tech", "news"],
    author: { $ne: "guest" },
  },
});

// Access results
console.log(data.value?.entries); // Article[]
console.log(data.value?.count); // number (if includeCount: true)

useGetAsset

Fetch single asset by UID.

const { data } = await useGetAsset<Asset>({
  assetUid: "your_asset_uid",
  locale: "en-us",
});

useGetAssets

Fetch multiple assets with filtering.

const { data } = await useGetAssets<Asset>({
  locale: "en-us",
  limit: 20,
  orderBy: "created_at",
  includeCount: true,
  where: {
    content_type: "image/jpeg",
    // Note: Most asset filters are applied client-side
  },
});

Query Operators

Supported in where clause for entry composables:

• Exact match: field: "value"
• Array contains: tags: ["tech", "news"]
• Comparison: field: { $gt: 100, $gte: 50, $lt: 200, $lte: 150, $ne: "value" }
• Existence: field: { $exists: true }
• Regex: field: { $regex: "pattern" }

useImageTransform

Transform Contentstack images programmatically.

const { transformedUrl, updateTransform, resetTransform } = useImageTransform(
  imageUrl,
  {
    width: 800,
    height: 600,
    quality: 80,
    format: "webp",
    fit: "crop",
    blur: 5,
    saturation: 10,
    brightness: 5,
    overlay: {
      relativeURL: "/watermark.png",
      align: "bottom-right",
      width: "20p",
    },
    sharpen: {
      amount: 5,
      radius: 2,
      threshold: 0,
    },
  }
);

// Update reactively
updateTransform({ width: 1200, quality: 90 });

Components

ContentstackModularBlocks

Renders Contentstack modular blocks as Vue components with optional auto-fetch capability. Auto-fetch is disabled by default. To enable auto-fetch, provide both contentTypeUid and url props. When using pre-fetched blocks, pass blocks via the blocks prop without providing contentTypeUid or url.

undefinedPattern 1: Auto-fetch Entryundefined

<script setup>
const componentMapping = {
  hero: Hero,
  grid: Grid,
  text_block: TextBlock,
};
</script>

<template>
  <ContentstackModularBlocks
    content-type-uid="page"
    :url="$route.path"
    blocks-field-path="components"
    :reference-field-path="['author']"
    :json-rte-path="['rich_text']"
    :auto-seo-meta="true"
    :component-map="componentMapping"
  >
    <template #loading>Loading...</template>
    <template #error>Failed to load</template>
    <template #empty>No content</template>
  </ContentstackModularBlocks>
</template>

undefinedPattern 2: Pre-fetched Blocksundefined

<script setup>
const { data: page } = await useGetEntryByUrl({
  contentTypeUid: "page",
  url: useRoute().path,
});

const componentMapping = {
  hero: Hero,
  grid: Grid,
};
</script>

<template>
  <ContentstackModularBlocks
    :blocks="page.components"
    :component-map="componentMapping"
  />
</template>

Props

Prop	Type	Default	Description
blocks	ContentstackBlock[]	[]	Array of modular blocks
componentMap	ComponentMapping	{}	Block type → Vue component mapping
fallbackComponent	Component	ContentstackFallbackBlock	Component for unmapped blocks
contentTypeUid	string	undefined	Content type for auto-fetch (required if using auto-fetch)
url	string	undefined	URL for auto-fetch (required if using auto-fetch)
blocksFieldPath	string	'components'	Field path to extract blocks
referenceFieldPath	string[]	[]	Reference fields to include
jsonRtePath	string[]	[]	JSON RTE field paths
locale	string	'en-us'	Locale
replaceHtmlCslp	boolean	editableTags	Replace HTML CSLP tags
seoMeta	SeoMetaInput	-	SEO metadata (passed to useSeoMeta)
autoSeoMeta	boolean | Record<string, string>	false	Auto-generate SEO from entry
containerClass	string	'contentstack-modular-blocks'	Container CSS class
emptyBlockClass	string	'visual-builder__empty-block-parent'	Empty block CSS class
showEmptyState	boolean	true	Show empty state
keyField	string	'_metadata.uid'	Key field for blocks
autoExtractBlockName	boolean	true	Auto-extract block name

SEO Metadata

undefinedManual SEO:undefined

<ContentstackModularBlocks
  :seo-meta="{
    title: 'Page Title',
    description: 'Page description',
    ogImage: 'https://example.com/image.jpg',
  }"
/>

undefinedAuto-generate SEO:undefined

<!-- Default field mapping -->
<ContentstackModularBlocks :auto-seo-meta="true" />

<!-- Custom field mapping -->
<ContentstackModularBlocks
  :auto-seo-meta="{
    title: 'seo_title|title|name',
    description: 'meta_description|description',
    ogImage: 'featured_image.url',
  }"
/>

Default auto-SEO mapping:

• title: seo_title → title → name
• description: seo_description → description → summary
• ogImage: featured_image.url → og_image.url → image.url

Slots

• loading - Custom loading state (auto-fetch mode)
• error - Custom error state (auto-fetch mode)
• empty - Custom empty state

ContentstackFallbackBlock

Built-in fallback component for unmapped block types. Displays block title, type badge, and props as formatted JSON.

@nuxt/image Integration

undefinedNote: This module requires @nuxt/image version 2.0.0 or higher. Make sure you have it installed before using the Contentstack image provider.

Setup

The @nuxt/image module should already be installed as a peer dependency. If not, install it:

npm install @nuxt/image@^2.0.0

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["nuxt-contentstack", "@nuxt/image"],

  image: {
    providers: {
      contentstack: {
        name: "contentstack",
        provider:
          "node_modules/nuxt-contentstack/dist/runtime/providers/contentstack",
      },
    },
    provider: "contentstack", // Optional: set as default
  },
});

Usage

<template>
  <!-- Basic usage -->
  <NuxtImg
    :src="image.url"
    :alt="image.title"
    width="800"
    height="400"
    :modifiers="{ auto: 'webp,compress', quality: 90 }"
    provider="contentstack"
  />

  <!-- Responsive -->
  <NuxtImg
    :src="image.url"
    sizes="100vw sm:50vw lg:33vw"
    :modifiers="{ auto: 'webp,compress' }"
  />

  <!-- Art direction -->
  <NuxtPicture
    :src="image.url"
    sizes="100vw md:50vw"
    :modifiers="{ auto: 'webp,compress' }"
  />
</template>

Supported Modifiers

• auto: 'webp' | 'webp,compress'
• quality: number
• format: 'webp' | 'png' | 'jpg' | 'jpeg' | 'gif' | 'auto'
• width, height, dpr: number
• fit: 'bounds' | 'crop'
• blur, brightness, contrast, saturation: number
• sharpen: { amount, radius, threshold }
• overlay: { relativeURL, align, repeat, width, height, pad }

Development

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with playground
npm run dev

# Build playground
npm run dev:build

# Lint
npm run lint

# Test
npm run test
npm run test:watch

# Release
npm run release