@voicenter-team/umbraco-headless-nuxt v0.0.15

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

title: Getting Started

Nuxt 3 Umbraco Headless Module 🚀

This module is specifically designed for Nuxt 3, utilizing Vue 3 and Nuxt 3's modern features to provide seamless integration with Umbraco CMS. It simplifies the process of fetching and managing content directly from Umbraco into your Nuxt project.

🌟 Features

• 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: Prefetch essential data to speed up your site.

🛠 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

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