@p8marketing/arboretum-sdk v0.0.5

Introduction

@p8marketing/arboretum-sdk is a library for building sitemaps in Contentful.

• Dynamic: Arboretum SDK builds sitemap dynamically based on the pages structure defined in Contentful. There are no hard-coded paths, so editors have full power over the sitemap.
• Customizable: Content types that represent pages are configurable, so you can integrate Arboretum SDK even in existing projects.
• Efficient: Number of requests to Contentful is minimalized.
• Lazy: By default sitemap is built only for locales that were explicitly requested.
• In memory: Sitemap is stored in memory, so no other dependencies (e.g. database) are required.

Installation

To install the stable version:

yarn add @p8marketing/arboretum-sdk

Create client

Basically, there are 3 ways to create Arboretum SDK client:

• By providing required credentials by hand

import { createArboretumClientFromCdaParams } from "@p8marketing/arboretum-sdk";

(async () => {
  const { client, warnings } = await createArboretumClientFromCdaParams({
    preview: false,
    contentful: {
      space: "[CONTENTFUL SPACE]",
      environment: "[CONTENTFUL ENVIRONMENT]",
      accessToken: "[CONTENTFUL CDA/CPA ACCESS TOKEN]",
      // Sample page content type configuration
      options: {
        pageContentTypes: {
          page: {
            titleFieldId: "name",
            slugFieldId: "slug",
            childPagesFieldId: "childPages",
          },
        },
      },
    },
    // Client configuration options
    options: {},
  });
})();

• By providing contentful CDA client

import { createArboretumClientFromCdaClient } from "@p8marketing/arboretum-sdk";
import { createClient } from "contentful";

const contentfulClient = createClient({
  space: "[CONTENTFUL SPACE]",
  environment: "[CONTENTFUL ENVIRONMENT]",
  accessToken: "[CONTENTFUL CDA/CPA ACCESS TOKEN]",
});

(async () => {
  const { client, warnings } = await createArboretumClientFromCdaClient({
    preview: false,
    contentful: {
      client: contentfulClient,
      // Sample page content type configuration
      options: {
        pageContentTypes: {
          page: {
            titleFieldId: "name",
            slugFieldId: "slug",
            childPagesFieldId: "childPages",
          },
        },
      },
    },
    // Client configuration options
    options: {},
  });
})();

• By providing contentful CMA client (especially useful in contentful apps)

import { createArboretumClientFromCma } from "@p8marketing/arboretum-sdk";
import { createClient } from "contentful-management";

async () => {
  const cmaClient = createClient({
    accessToken: "[CONTENTFUL CDA/CPA ACCESS TOKEN]",
  });

  const spaceClient = await cmaClient.getSpace("[CONTENTFUL SPACE]");

  const environmentClient = await spaceClient.getEnvironment(
    "[CONTENTFUL ENVIRONMENT]"
  );

  const { client, warnings } = await createArboretumClientFromCma({
    preview: false,
    contentful: {
      client: environmentClient,
      // Sample page content type configuration
      options: {
        pageContentTypes: {
          page: {
            titleFieldId: "name",
            slugFieldId: "slug",
            childPagesFieldId: "childPages",
          },
        },
      },
    },
    // Client configuration options
    options: {},
  });
};

In this step all data required to calculate sitemap is fetched and stored in internal memory. That's the only place where dynamic requests to Contentful are happening. All subsequent interactions with the Arboretum SDK client rely on the data fetched in this step.

*** Important: Remember to provide valid content types configuration unique to your contentful environment and mark entry representing the home page with the tag pageHome (you can customize this tag using homePageTagId configuration).

Client configuration options

Contentful configuration options

Contentful page content types configuration

Contentful redirect content type configuration

Basic usage

Most of the results returned by Arboretum SDK are wrapped by Eider (inspired by fp-ts Eider) where successful responses are marked with _tag equal to "Right" and failed responses are marked with _tag equal to "Left".

const homePage = client.pageByPath("/en");
console.log(homePage);
/* prints 
  {
    _tag: 'Right',
    right: {
      type: 'page',
      id: 'ZCFBfxFPfz3iy9Rojvxva',
      title: 'home',
      localeCode: 'en',
      path: '/en',
      slug: 'home',
      totalDirectChildrenCount: 2
    }
  }

or

  { _tag: 'Left', left: 'Failed to find locale by code: en' }
  
 */

const blogPage = client.pageById("en", "4bkXR9tM8c1cGzTe7BMIgn");
console.log(blogPage);
/* prints 
  {
    _tag: "Right",
    right: {
      type: "page",
      id: "4bkXR9tM8c1cGzTe7BMIgn",
      title: "blog",
      localeCode: "en",
      path: "/en/blog",
      slug: "blog",
      totalDirectChildrenCount: 2,
    },
  }

or

  {
    _tag: "Left",
    left: "Failed to find page by id: 4bkXR9tM8c1cGzTe7BMIgn and locale: en",
  }
  
 */

Documentation

• Arboretum SDK Documentation