Agnostic CMS Harmonizer

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

Find the latest package version on the One Beyond NPM Registry

Quick Start

Install the library via npm:

npm i @onebeyond/agnostic-cms-harmonizer
Copy

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' });
Copy

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)
Copy

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

await client.init();
Copy

Now use the harmonizer methods of the cmsCLient.

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

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

Enjoy!

Development

CLI

Install Contentful CLI or alternatively use npx contentful-cli

Environment Variables

1. You have to create a space in contentful to run the tests.
2. Follow the instructions here to create an API key.
3. 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
Copy

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.

Login to Contentful and import test content with the CLI:

contentful 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>
Copy

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>
Copy

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>
Copy

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>
Copy

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.

Run the test suites

• Run unit tests

npm run test
Copy

• Run end to end tests

npm run test:e2e
Copy

Documentation

The project uses tsdoc to generate the technical documentation from the source code.

• Build the documentation

npm run docs:build
Copy

• Run in watch mode to look for file changes and update immediately

npm run docs:build:watch
Copy

• Serve the build output statically

npm run docs:serve
Copy

Community

• We are open to improvements in the issues section.
• Check the wiki for more context on the internal workings of this library.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Íñigo Marquínez Prado 💻 📖 👀

Àlex Serra 💻 ⚠️ 📖 👀

Matyas Angyal 👀 💻 📖 ⚠️

Ulises Gascón 👀

Roberto Hernández 💻 ⚠️ 📖 👀

This project follows the all-contributors specification. Contributions of any kind welcome!