CDP Libraries

A mono-repo containing libraries for the CDP (Core Delivery Platform) ecosystem. This mono-repo provides the ability to simply create and manage CDP packages, ensuring consistency and ease of use across different projects.

• Requirements
  • Node.js
• Local development
  • Setup
• Creating a new package
• Global tooling
• Testing your changes
• Automatically updating npm dependencies with Dependabot
• Manually updating npm dependencies
• Not releasing
• Releasing
• Changesets
• Release it

Requirements

To get started with the CDP Libraries mono-repo, you need to have Node.js and npm installed on your machine.

Node.js

Please install Node.js >= v22 and npm >= v9.

Tip

To install Node.js and npm Use Node Version Manager nvm

To use the correct version of Node.js for this mono-repo, via nvm:

cd cdp-libraries
nvm use

Local development

Setup

Install all dependencies:

npm install

Creating a new package

• Copy and rename an existing package in the packages directory to create a new package
• If they exist, remove coverage and node_modules directories from the new package
• If it exists, remove the CHANGELOG.md
• Empty the src folder in the new package
• Update the README.md file in the new package with relevant information about your package
• Update the package.json file in the new package with relevant information:
  • Update the name field to a unique name for your package
  • Update the version field to 0.0.1
  • Update the description field with a brief description of your package
  • Update the main field with the path to your entry point
  • Update the repository field with the URL of your new package's readme
  • Update the release-it object to include the new package. The config should be ok for you but you will need to use your new package name
• Update dependabot by running node scripts/generate-dependabot.js
• Now you have all you need to start developing your new package

Global tooling

The following tools are available for free from the root of cdp-libraries. You do not need to install these in your package.json file, as they are already included in the root package.json:

• vitest - for running tests
• neostandard - for linting code
• release-it - for managing releases
• prettier - for code formatting
• husky - for managing git hooks

Testing your changes

To test your changes in this repo in a local consuming codebase, npm link is your friend here. Have a read of https://docs.npmjs.com/cli/v9/commands /npm-link

Automatically updating npm dependencies with Dependabot

Dependabot is configured to automatically create pull requests to update npm dependencies in the root package and all packages. These pull requests will be created automatically when new versions of dependencies are released and the specified cooldown period has passed. As a CDP developer you simply need to merge these pull requests when they have been created and have passed all required checks.

Once the dependabot PR's have been merged you will need to release the packages that have had their dependencies updated. You can do this by creating a new changeset via npm run changeset and merging this PR.

Manually updating npm dependencies

To update npm dependencies in the root package and all packages, you can use the following command from the root of the mono-repo:

npm run update:deps

This will use npm-check-updates to update all dependencies to their latest versions.

You then need to install these updates via:

npm install

and commit the changes and release as appropriate.

Not releasing

If you have changes you wish to commit but do not want to release a new version of the package, or tag and release the package on GitHub. You can simply just make your commits as normal and raise a PR. There is no need to create a changeset. This is usually documentation or items in the root that do not need to be published.

Tip

For any changes in the packages directory, you should always create a changeset so they are released when your PR is merged

Releasing

The GitHub release workflow is intended to authenticate with npm using OIDC Trusted Publishers. For the first release you may need to push the empty project manually using your own npm credentials for the project to be created an then enable OIDC. See the docs for information on how to set this up.

TL;DR: Releasing a new version of a package is as simple as running npm run changeset in root directory and merging a PR.

• Developer writes changeset
• Chooses correct bump for changes
• CI does everything else. Versions, tags, releases and publishes

Read on for detailed instructions. Releasing to npm and tagging on GitHub is done using the changeset and release-it tools, which is configured in the root of the workspace. This is super simple and all you need to do is:

After you have commited your work and are ready to release a new version of your package:

• Run npm run changeset to create a new changeset
• Commit the changeset file that was created in the .changeset directory
• Raise a PR with the changes you want to release
• Wait for status required checks to pass
• Get the PR reviewed and approved by at least one other developer
• Get an approval from the cdp-libraries owners
• Merge the PR into main branch
• The cdp-libraries GitHub Action will automatically run the changeset and release-it tool, which will:
  • Bump the version number in the package.json file
  • Create a new tag and release in GitHub with the new version number
  • Push the changes to the main branch
  • Publish the package to npm

Changesets

This project uses changeset for managing versioning of packages. This is already set up to go and works on CI automatically.

Release it

This project uses release-it for managing releases. It automates the process of tagging and releasing to GitHub. It is set up to go.