@grace-studio/umbraco-client v1.0.0

@grace-studio/umbraco-client

A middle layer that connects your application to the Umbraco CMS using a simple and flexible API client.

Features

• Easy Integration: Seamlessly integrate Umbraco CMS with your app.
• TypeScript Support: Automatically generate types from your Umbraco Swagger schema.
• Flexible API: Provides methods to fetch, format, and filter content efficiently.

Installation

Install the package using npm or yarn:

# Using npm
npm install @grace-studio/umbraco-client

# Using yarn
yarn add @grace-studio/umbraco-client

Generate TypeScript Types

Before using the client, generate TypeScript types based on your Umbraco Swagger schema. This ensures type safety when interacting with the Umbraco API.

npx openapi-typescript https://your-umbraco-url/swagger/v1/swagger.json --output ./src/api/types.ts

This command will generate TypeScript definitions for your Umbraco API and save them in ./src/api/types.ts.

If running into issues with self-signed SSL certificate locally

Add the environment variable NODE_TLS_REJECT_UNAUTHORIZED=0 to tell Node.js to ignore SSL certificate validation. This is useful for local development when working with a self-signed certificate or localhost.

NODE_TLS_REJECT_UNAUTHORIZED=0 npx openapi-typescript https://your-umbraco-url/swagger/v1/swagger.json --output ./src/api/types.ts

Usage

Below is an example of how to use the UmbracoClient in your Next.js application.

Setup the API Client

import type { components, paths } from '#api/types';
import { UmbracoClient } from '@grace-studio/umbraco-client';

// Create an instance of UmbracoClient
const apiClient = UmbracoClient.create<paths>({
  apiToken: 'your-api-token', // Replace with your actual API token
  apiUrl: 'https://your-umbraco-url', // Your Umbraco API URL
});

Example API Methods

Here are some common use cases for fetching content from the Umbraco CMS using the UmbracoClient.

Fetch All Content

const getContent = () =>
  apiClient
    .get('/umbraco/delivery/api/v2/content')
    .then(UmbracoClient.format.content); // Format the content

Fetch a Specific Content Item by Path

const getContentItem = (path: string) =>
  apiClient
    .get('/umbraco/delivery/api/v2/content/item/{path}', {
      params: {
        path: { path }, // Pass the path as a parameter
      },
    })
    .then(UmbracoClient.format.contentItem); // Format the specific content item

Fetch Content Paths

const getPaths = (
  basePath: string, // Base path, eg. your locale '/en'
) =>
  apiClient.getPaths({
    basePath,
    excludeHidden: true, // Exclude hidden content
    mappingFunctions: {
      // Add custom mapping functions for hidden content based on properties
      hidden: ({ umbracoNaviHide }) => Boolean(umbracoNaviHide),
    },
    extraQueryParams: {
      sort: 'sortOrder:desc', // Possible to add extra query params to pass to Umbraco
    },
  });

Fetch Content Menu

const getMenu = (
  basePath: string, // Base path, eg. your locale '/en'
) =>
  apiClient.getMenu({
    basePath,
    excludeHidden: true, // Exclude hidden content
    mappingFunctions: {
      // Add custom mapping functions for hidden content based on properties
      hidden: ({ umbracoNaviHide }) => Boolean(umbracoNaviHide),
    },
    properties: {
      // Custom functions to map properties from raw content to menu items
      menuBlock: ({ menuBlock }) => menuBlock,
      type: ({ isSecondaryLink }) =>
        isSecondaryLink === true ? 'secondary' : 'primary',
    },
    extraQueryParams: {
      // Specify the properties needed.
      // Tip: Do NOT specify properties that you don't need since the total data transfer can be rather large.
      fields: 'properties[umbracoNaviHide,isSecondaryLink,menuBlock]',
      // Amount of records to return
      take: '9999',
    },
    headers: {
      // Custom headers
      Preview: true,
    },
  });