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

| 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 | [] |

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 |

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 |