![](\"./logo.svg\"){kind=logo}
\n \n\n \n\nArboretum - The sitemap for Contentful\n
\n\n# Introduction\n\n`@bright.global/arboretum-sdk` is a library for building sitemaps in [Contentful](https://www.contentful.com/).\n\n- **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.\n- **Customizable:** Content types that represent pages are configurable, so you can integrate Arboretum SDK even in existing projects.\n- **Efficient:** Number of requests to Contentful is minimalized.\n- **Lazy:** By default sitemap is built only for locales that were explicitly requested.\n- **In memory:** Sitemap is stored in memory, so no other dependencies (e.g. database) are required.\n\n# Installation\n\nTo install the stable version:\n\n```\nyarn add @bright.global/arboretum-sdk\n```\n\n# Create client\n\nBasically, there are 3 ways to create Arboretum SDK client:\n\n- By providing required credentials by hand\n\n```ts\nimport { createArboretumClientFromCdaParams } from \"@bright.global/arboretum-sdk\";\n\n(async () => {\n const { client, warnings } = await createArboretumClientFromCdaParams({\n preview: false,\n contentful: {\n space: \"[CONTENTFUL SPACE]\",\n environment: \"[CONTENTFUL ENVIRONMENT]\",\n accessToken: \"[CONTENTFUL CDA/CPA ACCESS TOKEN]\",\n // Sample page content type configuration\n options: {\n pageContentTypes: {\n page: {\n titleFieldId: \"name\",\n slugFieldId: \"slug\",\n childPagesFieldId: \"childPages\",\n },\n },\n },\n },\n // Client configuration options\n options: {},\n });\n})();\n```\n\n- By providing contentful CDA client\n\n```ts\nimport { createArboretumClientFromCdaClient } from \"@bright.global/arboretum-sdk\";\nimport { createClient } from \"contentful\";\n\nconst contentfulClient = createClient({\n space: \"[CONTENTFUL SPACE]\",\n environment: \"[CONTENTFUL ENVIRONMENT]\",\n accessToken: \"[CONTENTFUL CDA/CPA ACCESS TOKEN]\",\n});\n\n(async () => {\n const { client, warnings } = await createArboretumClientFromCdaClient({\n preview: false,\n contentful: {\n client: contentfulClient,\n // Sample page content type configuration\n options: {\n pageContentTypes: {\n page: {\n titleFieldId: \"name\",\n slugFieldId: \"slug\",\n childPagesFieldId: \"childPages\",\n },\n },\n },\n },\n // Client configuration options\n options: {},\n });\n})();\n```\n\n- By providing contentful CMA client (especially useful in contentful apps)\n\n```ts\nimport { createArboretumClientFromCma } from \"@bright.global/arboretum-sdk\";\nimport { createClient } from \"contentful-management\";\n\nasync () => {\n const cmaClient = createClient({\n accessToken: \"[CONTENTFUL CDA/CPA ACCESS TOKEN]\",\n });\n\n const spaceClient = await cmaClient.getSpace(\"[CONTENTFUL SPACE]\");\n\n const environmentClient = await spaceClient.getEnvironment(\n \"[CONTENTFUL ENVIRONMENT]\"\n );\n\n const { client, warnings } = await createArboretumClientFromCma({\n preview: false,\n contentful: {\n client: environmentClient,\n // Sample page content type configuration\n options: {\n pageContentTypes: {\n page: {\n titleFieldId: \"name\",\n slugFieldId: \"slug\",\n childPagesFieldId: \"childPages\",\n },\n },\n },\n },\n // Client configuration options\n options: {},\n });\n};\n```\n\nIn 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.\n\n*** 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). \n\n### Client configuration options\n\n| | Default | Description |\n| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 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. |\n| 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. |\n| 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. |\n\n### Contentful configuration options\n\n| Default | Default | Description |\n|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| homePageTagId | pageHome | Sitemap root tag id |\n| pageContentTypes | | **Required**. Object consisting of keys that are content type id's and values described [here](#contentful-page-content-types-configuration). Sample value: `{page:{\"titleFieldId\":\"name\",\"slugFieldId\":\"slug\",\"childPagesFieldId\":\"childPages\"}}` |\n| redirectContentType | | Object described [here](#contentful-redirect-content-type-configuration). Sample value: `{\"id\":\"redirect\",\"titleFieldId\":\"name\",\"typeFieldId\":\"type\",\"pageFieldId\":\"page\",\"pathFieldId\":\"path\"}` |\n### Contentful page content types configuration\n| Name | Default | Description |\n|-------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| titleFieldId | | Id of the field that represents the page title. This field should be of type `Symbol`. |\n| 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`. |\n| 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. |\n| select | | Array of additional field ids that should be fetched and exposed on pages via `additionalFields`. |\n### Contentful redirect content type configuration\n| Name | Default | Description |\n|--------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id | | **Required**. Id of the redirect content type. |\n| titleFieldId | | Id of the field that represents the redirect title. This field should be of type `Symbol`. |\n| typeFieldId | | **Required**. Id of the field that represents the redirect type (should be either `alias` or `redirect`). This field should be of type `Symbol`. |\n| 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. |\n| 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`. |\n| select | | Array of additional field ids that should be fetched and exposed on redirects/aliases via `additionalFields`. |\n\n# Basic usage\n\nMost of the results returned by Arboretum SDK are wrapped by `Either` (inspired by [fp-ts Either](https://gcanti.github.io/fp-ts/modules/Either.ts)) where successful responses are marked with `_tag` equal to `\"Right\"` and failed responses are marked with `_tag` equal to `\"Left\"`.\n\n```ts\nconst homePage = client.pageByPath(\"/en\");\nconsole.log(homePage);\n/* prints \n {\n _tag: 'Right',\n right: {\n type: 'page',\n id: 'ZCFBfxFPfz3iy9Rojvxva',\n title: 'home',\n localeCode: 'en',\n path: '/en',\n slug: 'home',\n totalDirectChildrenCount: 2\n }\n }\n\nor\n\n { _tag: 'Left', left: 'Failed to find locale by code: en' }\n \n */\n\nconst blogPage = client.pageById(\"en\", \"4bkXR9tM8c1cGzTe7BMIgn\");\nconsole.log(blogPage);\n/* prints \n {\n _tag: \"Right\",\n right: {\n type: \"page\",\n id: \"4bkXR9tM8c1cGzTe7BMIgn\",\n title: \"blog\",\n localeCode: \"en\",\n path: \"/en/blog\",\n slug: \"blog\",\n totalDirectChildrenCount: 2,\n },\n }\n\nor\n\n {\n _tag: \"Left\",\n left: \"Failed to find page by id: 4bkXR9tM8c1cGzTe7BMIgn and locale: en\",\n }\n \n */\n```\n\n# Documentation\n\n- [Arboretum SDK Documentation](https://brightit.github.io/arboretum-sdk/)\n","readmeFilename":"README.md"}