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

| Option | Description | Required | Default | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|----------|---------| | getUmbracoDataAPI | URL for requests to fetch Umbraco data. | Yes | - | | generateUmbracoDataAPI | URL for requests to generate sitemap.xml, robots.txt, umbracoData.json. | Yes | - | | site | The name of your website. | Yes | - | | trailingSlashRedirect | Enables a 301 redirection to URLs without trailing slashes. | No | false | | prefix | Prefix for generated routes, useful for multi-language sites. | No | '' | | redirects | Contains sub-options for configuring redirects (detailed below). | No | - | | prefetch | Prefetch content and set it to global (detailed below) | No | [] | | compatibilityMode | Force Nuxt major version resolution: 'auto' (default), 'nuxt3', or 'nuxt4'. See Nuxt 3/4 compatibility. | No | 'auto'| | paths | Override auto-detected paths (detailed below). | No | - | | performance | Performance / build-time options (detailed below). | No | - |

Redirects Configuration

| Sub-Option | Description | Default | |---------------------------|-------------------------------------------------------------------------------|---------| | enable | Whether to enable 301 redirects. | false | | redirectFolderName | Umbraco Data content type name where redirects are stored. | redirectFolder | | rootChildrenUmbracoPath | Path of children content for redirect matching. | SiteData.children | | enableInDevelopment | Allows redirects in development mode. | false |

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.

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.

| Sub-Option | Description | Default | |-------------|------------------------------------------------------------------------|-------------------------| | srcDir | Absolute path to the project srcDir. | nuxt.options.srcDir | | pagesDir | Pages directory name relative to srcDir. | nuxt.options.dir.pages (pages in N3, app/pages in N4) | | publicDir | Public directory name relative to rootDir. | nuxt.options.dir.public (public) |

Performance Configuration

| Sub-Option | Description | Default | |---------------------|------------------------------------------------------------------------------------|------------------------------------------| | apiTimeout | HTTP request timeout in ms. 0 disables the timeout and waits until the server responds (recommended for slow Umbraco APIs). | 0 (disabled) | | apiRetries | Number of retries for failed HTTP requests. For a slow API retries just multiply the wait time. | 0 | | parallelFetch | Fetch JSON data, robots.txt and sitemap.xml in parallel. | true | | cacheApiResponses | Cache Umbraco API responses on disk between builds to speed up repeated dev/build. | false | | cacheTtlMs | Cache lifetime in ms when cacheApiResponses is enabled. | 300000 (5 min) | | cacheDir | Cache directory relative to rootDir. | node_modules/.cache/umbraco-headless | | useTypeTemplate | Register umbraco types via addTypeTemplate. Set false to write legacy public/global.d.ts. | true |

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

| Field | Type | Description | |---------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | fetch | Object | Contains parameters for the fetching process. Check Parameters | | globalKey | String | The key under which fetched data is stored globally for access across the application. |

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

| Parameter | Type | Required | Description | |-------------|--------|----------|-------------| | fetch | object | Yes | Check Parameters| | ignore | Array | No | Specifies keys to be ignored in the fetched data. Includes key (keys to ignore) and excludeStartLevel (level from which to start ignoring). | | include | Array | No | Specifies keys to be explicitly included in the final data. | | index | String | No | Optional, The name of page component. Using for type definition of the fetched data.

Fetch Object Configuration

| Field | Type | Description | |---------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | type | String | Type of fetching operation. Possible values: contentType: Fetches data based on content type.path: Fetches data based on a JSON path. | | pattern | String | Identifier used to specify the content to fetch: If type is contentType, use the name of the ContentType corresponding to your content management system's configuration.If type is path, use the JSONPath of the page. Typically sourced from nuxtApp._route.meta.Jpath |