@voicenter-team/umbraco-headless-nuxt

title: Getting started description: Nuxt 3 / Nuxt 4 Umbraco Headless Module. navigation: title: Getting Started

Nuxt 3 & Nuxt 4 Umbraco Headless Module 🚀

This module provides seamless integration with Umbraco CMS for Nuxt projects. It supports both Nuxt 3 (3.13+) and Nuxt 4, automatically detecting the active Nuxt version and adapting path resolution (srcDir, pagesDir, publicDir) accordingly — no manual configuration required.

🌟 Features

• Nuxt 3 & Nuxt 4 Compatibility: Auto-detects Nuxt major version via future.compatibilityVersion and handles the Nuxt 4 app/ directory layout out of the box.
• Easy Integration with Umbraco CMS: Configure once and fetch content with minimal overhead.
• Dynamic Route Generation: Automatically generate routes based on your Umbraco CMS content.
• Advanced Redirect Handling: Manage SEO-friendly redirects easily through your CMS.
• Performance Optimizations: Parallel API fetching, on-disk response caching, configurable timeouts and retries.
• Small footprint: Uses ofetch (native to Nuxt) instead of axios; externalises peer deps to keep the shipped bundle lean.
• Generated umbraco types via addTypeTemplate: Types are registered through Nuxt's virtual type system instead of being written into /public.

🛠 Installation

npm install @voicenter-team/umbraco-headless-nuxt
# OR
yarn add @voicenter-team/umbraco-headless-nuxt

⚙ Configuration

Add the module to your nuxt.config.ts and configure the options as shown in the tables below:

// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  modules: [
    '@voicenter-team/umbraco-headless-nuxt'
  ],
  umbracoHeadless: {
    getUmbracoDataAPI: 'https://your-umbraco-api-url',
    generateUmbracoDataAPI: 'https://files-generation-url',
    site: 'your-site-name',
    trailingSlashRedirect: false,
    prefix: '',
    redirects: {
      enable: false,
      redirectFolderName: 'redirectFolder',
      rootChildrenUmbracoPath: 'SiteData.children',
      enableInDevelopment: false
    },
    prefetch: [
      {
        fetch: {
          type: 'contentType',
          pattern: 'websiteMainNavigation'
        },
        globalKey: 'websiteMainNavigation'
      }
      // Additional prefetch configurations can be added here
    ]
  }
})

📊 Configuration Options

Redirects Configuration

The redirect server handler is registered as global Nitro middleware (no explicit route), so Cloudflare Pages keeps applying its native _redirects rules for static routes while the middleware still runs inside the Worker for SSR routes. The generated public/_redirects file is published as part of Nuxt's standard public-directory pipeline.

Sitemap Configuration

By default, the module fetches sitemap XML from the Umbraco sitemap endpoint and filters it before writing public/sitemap.xml. This does not affect route generation: pages excluded from the sitemap can still be generated as Nuxt routes.

umbracoHeadless: {
  // ...required options
  sitemap: {
    enabled: true,
    removeWhenDisabled: false,
    excludeNoIndex: true,
    excludeHidePage: false
  }
}

Paths Configuration

All fields are optional. When omitted, the module uses Nuxt's own srcDir / dir.pages / dir.public, which means it works with both the Nuxt 3 (pages/, public/ at project root) and the Nuxt 4 (app/pages/, public/ at project root) layouts automatically.

Performance Configuration

Example with all performance knobs enabled:

umbracoHeadless: {
  // ...required options
  performance: {
    // 0 (default) disables the timeout. Set a positive value only if you
    // want `nuxt prepare` to fail fast on an unresponsive Umbraco API.
    apiTimeout: 0,
    // 0 (default) — no retries. Increase only if your API is flaky.
    apiRetries: 0,
    parallelFetch: true,
    cacheApiResponses: true,
    cacheTtlMs: 10 * 60 * 1000
  }
}

🧭 Nuxt 3 / Nuxt 4 compatibility

• The module requires Nuxt ^3.13.0 || ^4.0.0 (declared as a peer dependency).
• Nuxt version is detected at module setup via nuxt.options.future.compatibilityVersion. When it is 4 (or the running Nuxt major is 4), the module:
  • resolves pages from app/pages (or whatever nuxt.options.dir.pages is set to),
  • resolves the public directory from nuxt.options.dir.public,
  • skips legacy /public/global.d.ts generation and instead ships types through addTypeTemplate.
• You can override detection explicitly:

umbracoHeadless: {
  compatibilityMode: 'nuxt4', // 'auto' | 'nuxt3' | 'nuxt4'
  paths: {
    // Optional — only needed for non-standard project layouts.
    // srcDir: '/abs/path/to/src',
    // pagesDir: 'pages',
    // publicDir: 'public'
  }
}

Route Meta Object Modification

The module modifies the route meta object to include specific properties that facilitate data fetching for different routes. Below is the structure of the modified route meta object:

Modified Route Meta Object Structure

  {
     nodeID: 14525,
     url: '/about-us/security',
     Jpath: '$.children.broshurePages_28_14450.children.broshurePageTemplate_3_14525',
     TemplateAlias: "BroshurePageTemplate"
  }

Prefetch Configuration Guide

This guide details the prefetch configuration used in your application. The configuration allows for data to be fetched preemptively based on specified criteria and stored globally for easy access throughout the application.

Configuration Overview

Each prefetch object within the prefetch array specifies a strategy for fetching data. Here's a detailed breakdown of each field:

Configuration Fields

Example Configuration

Below is an example of how to configure the prefetch of main navigation data based on content type:

{
  prefetch: [
    {
      fetch: {
        type: "contentType",
        pattern: "websiteMainNavigation"
      },
      globalKey: "websiteMainNavigation"
    }
    // Additional prefetch configurations can be added here
  ]
}

Example of how to configure the prefetch of Product Main Page data based on path:

{
  prefetch: [
    {
      fetch: {
        type: "path",
        pattern: "$.children.productPageMain_5_12551"
      },
      globalKey: "yourGlobalKey"
    }
    // Additional prefetch configurations can be added here
  ]
}

📘 Usage

Accessing Prefetched Data from Global Store:

Get Data by Key

To retrieve data stored under a specific key from the global store, use the useUmbracoStoreGetByKey() composable. This is particularly useful when you know the key associated with the data you need, as configured in your prefetch settings.

<script setup lang="ts">
  // Get data from store configured in nuxt.config.ts file under UmbracoHeadless.prefetch
  const getStoreDataByKey = useUmbracoStoreGetByKey();
  const keyData = getStoreDataByKey('yourGlobalKey');
</script>

Get All Data from Store

If you need to access all data stored in the global store, you can use the useUmbracoStoreGetAllData() composable. This method retrieves all data objects stored, allowing for more generic queries or when multiple pieces of data need to be utilized.

<script setup lang="ts">
  // Get all store data
  const getAllStoreData = useUmbracoStoreGetAllData();
  const allStoreData = getAllStoreData();
</script>

Fetching Content

This section explains two methods for fetching data within a Nuxt application: by path and by content type. Each method includes required and optional parameters to tailor data fetching to your needs.

1. Fetching by Path

Fetch data based on a JSON path specified in the route's meta object, with options to ignore or include specific keys.

Function Call Example

<script setup lang="ts">
  const nuxtApp = useNuxtApp()
  const getContent = useUmbracoGetContent()
  
  const {data} = useAsyncData(() => {
  return getContent({
    fetch: {
      type: 'path',
      pattern: nuxtApp._route.meta.Jpath,
    },
    ignore: [
      {
        key: ['children'],
        excludeStartLevel: 0
      }
    ],
    include: ['key1', 'key2']
  }, 'index')
});
</script>

2. Fetching by ContentType

Fetches data based on a specified content type, with options for ignoring and including certain data elements.

Function Call Example

<script setup lang="ts">
  const nuxtApp = useNuxtApp()
  const getContent = useUmbracoGetContent()
  
  const { data: contentTypeData } = useAsyncData(() => {
    return getContent({
      fetch: {
        type: 'contentType',
        pattern: 'yourContentTypeValue',
      },
    })
});
</script>

Parameters Description

Fetch Object Configuration