npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bright.global/arboretum-sdk

v0.1.0-rc.7

Published

The sitemap for contentful

Downloads

52

Readme

Introduction

@bright.global/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 @bright.global/arboretum-sdk

Create client

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

  • By providing required credentials by hand
import { createArboretumClientFromCdaParams } from "@bright.global/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 "@bright.global/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 "@bright.global/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

| | Default | Description | | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | eageryly | false | By default localized sitemap is generated only for locales that were explicitly requested. When set to true sitemap is generated for every locale in advance. | | data | | You can cache data computed during previous Arboretum SDK client initialization (client.cachedData method) and use it to create a new client. When this parameter is defined all requests to Contentful are skipped. | | includeEntryStatus | false | Only for Arboretum SDK clients that were created based on Contentful CMA. When set to true page's cmaOnlyStatus field will be defined. |

Contentful configuration options

| Default | Default | Description | |---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | homePageTagId | pageHome | Sitemap root tag id | | pageContentTypes | | Required. Object consisting of keys that are content type id's and values described here. Sample value: {page:{"titleFieldId":"name","slugFieldId":"slug","childPagesFieldId":"childPages"}} | | redirectContentType | | Object described here. Sample value: {"id":"redirect","titleFieldId":"name","typeFieldId":"type","pageFieldId":"page","pathFieldId":"path"} |

Contentful page content types configuration

| Name | Default | Description | |-------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | titleFieldId | | Id of the field that represents the page title. This field should be of type Symbol. | | slugFieldId | | Required. Id of the field that represents the page slug that should match the following regexp ^((\/)\|(([\/\w\-\._~:!$&'\(\)*+,;@]\|(%\d+))+))$. This field should be of type Symbol. | | childPagesFieldId | | Id of the field that represents the references to child pages. This field should be of type Array and include references to other entries that were configured as pages. |

Contentful redirect content type configuration

| Name | Default | Description | |--------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | | Required. Id of the redirect content type. | | titleFieldId | | Id of the field that represents the redirect title. This field should be of type Symbol. | | typeFieldId | | Required. Id of the field that represents the redirect type (should be either alias or redirect). This field should be of type Symbol. | | pageFieldId | | Required. Id of the field that represents the page reference. This field should be of type Link and accept references only to entries that were configured as pages. | | pathFieldId | | Required. Id of the field that represents the redirect path that should match the following regexp \/(\w+:{0,1}\w*@)?(\S+)(:[0-9]+)?$. This field should be of type Symbol. |

Basic usage

Most of the results returned by Arboretum SDK are wrapped by Either (inspired by fp-ts Either) 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