@onebeyond/agnostic-cms-harmonizer NPM

Agnostic CMS Harmonizer

An agnostic library to handle communication with multiple CMS in an agnostic way.

NPM Version GitHub Release Date

NPM Downloads all contributors LICENSE dependencies NPM Unpacked Size

Find the latest package version on the One Beyond NPM Registry

Documentation

TL;DR

Install the library via npm:

npm i @onebeyond/agnostic-cms-harmonizer

Use the harmonized providers:

 import { ContentfulClient } from '@onebeyond/agnostic-cms-harmonizer';
 
 const client = new ContentfulClient({
   accessToken,
   space,
   environment,
 });

 await client.init();

 const entry = await client.getEntry<MyEntry>({ entryId: '123' });

 const collection = await client.getCollection<MyCollection>({ collectionId: '123' });

The library exposes a common interface for multiple CMSs and outputs harmonized data instead raw responses.

Each CMS provider exposes the getEntry and getCollection methods to request one or multiple entries accordingly.

First, supply the vendor-related configuration parameters to the constructor:

const cmsClient = new CmsClient(vendorConfigurationObject)

The client instance must call the init() method to configure the provider before attempting to request data from the CMS:

await client.init();

Now use the harmonizer methods of the cmsCLient.

 const entry = await client.getEntry<MyEntry>({ entryId: '123' });

 const collection = await client.getCollection<MyCollection>({ collectionId: '123' });

Enjoy!

Development

CLI

Install Contentful CLI or alternatively use npx contentful-cli

Environment Variables

You have to create a space in contentful to run the tests.
Follow the instructions here to create an API key.

Setup your .env file as follows

CONTENTFUL_ACCESS_TOKEN=your_access_token
CONTENTFUL_ENVIRONMENT=your_environment
CONTENTFUL_SPACE=your_space
CONTENTFUL_ENTRY=your_entry
CONTENTFUL_CONTENT_TYPE=your_content_type

Testing

Import Content

To run the e2e tests you need to be authenticated in your contentful account and import the dummy content into the space you created before. The content you need to import is located at __tests__/exports/contentful/agnostic-cms-harmonizer_space.json and should not be updated.

contenful login

contentful space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Or by using NPX:

npx contentful-cli login

npx contentful-cli space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Export Content

To update the test content you need to export the updated content from Contentful.

Export the content using the CLI

contentful space export --config ./__tests__/exports/contentful/config.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Or by using NPX:

npx contentful-cli space export --config ./__tests__/exports/contentful/config.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Continous Integration

The pipeline is configured to use the Contentful space managed by the agnostic.cms.harmonizer@proton.me account during the E2E tests execution. If the content of these tests needs to be updated in the provider, you must have access to this vault, otherwise, you can open an issue referencing the new content exported.