Introduction

In this section, you will find the general documentation for the NPM packages within Codey.
More information about the maintenance plan for the codey platform can be found here.

WARNING

Before you can install any of these, you first need to follow the installation guide here.

Version tags

Packages can published with 2 different tags:

• @latest: latest stable / production-ready version release of a package
• @next: pre-release of a package, considered unstable and not production-ready.
  might become the next stable release once QA approved

Installing packages

Codey packages can be installed via npm from the @xerius organisation.

stable

# latest is the default tag...
npm i @xerius/codey-core

# ...but you're allowed to be explicit if you want:
npm i @xerius/codey-core@latest

pre-release

# next is tag to get the newest pre-release
npm i @xerius/codey-core@next

Upgrading packages

Checking for updates can be done using the npm check updates package. Install this package globally using npm i -g npm-check-updates and then run one of the following commands to upgrade the codey packages:

stable

# Upgrade to the latest stable versions (excl. pre-releases)
ncu -f '*xerius*' -u

pre-release

# Upgrade to the next versions (incl. pre-releases)
ncu -f '*xerius*' --target greatest -u

After running the command, you can inspect the changes to the package.json file.

Don't forget!

After you confirmed the changes are correct, you still need to run npm install to install the upgrades.

Redesign Migration Overview

Codey Packages

The following points provides an overview of the migration steps required:

1. Install the latest @xerius/codey-tailwind and follow the installation guide.
2. Install the latest @xerius/codey-assets and follow the migration guide found in the changelog. This mainly concerns migrating getCodeyImageUrl usages.
3. Install the latest @Xerius/codey-components.
4. Remove the @xerius/codey-style package as it is no longer required.
5. Update the related packages like @xerius/codey-cookiebot, @xerius/codey-hello-customer, @xerius/codey-core to the latest version and follow their migrations steps in the changelog.

INFO

The largest changes are in the @xerius/codey-components and @xerius/codey-tailwind package. To migrate the code successfully and using the maximum search capabilities of your IDE we suggest the following workflow:

1. Check the components changelog and update impacted components within your application.
   • Update components used within templates so they're all PascalCased conform the vue naming conventions.
     e.g. <xer-button> becomes <XerButton>.
   • All xer prefixes on component props are removed so the prop naming is the same as codey-components's adopted PrimeVue components.
2. Remove the xer- prefix used by tailwind classes in your application.
   e.g. xer-bg-primary becomes bg-primary.
   If all components are updated as described in the steps above, you can use the search and replace functionality to replace xer- with an empty string.

The last step is to update the colors and tailwind util class usages to the new tailwind configuration. Migration info is found in the changelog.

Other Packages

Besides the codey packages, you will likely need to update other dev and normal dependencies to be able to uphold correct versions between the packages. This exercise is already done on the codey starter and you can find interoperable versions in the package.json file:

• current package.json
• snapshot package.json just after redesign upgrades

Vue 2 Support

While we are migrating application to Vue 3, we decided to keep a Vue 2 version of our packages available. Once migrations are complete, we will deprecate the Vue 2 packages and remove them from the registry.

Packages

The Vue 2 packages names are suffixed with -vue2 and require a separate installation if they are needed.

Update your package.json with the following change to switch to the Vue 2 packages:

"dependencies": {
  "@xerius/codey-style": "^1.0.0",
  "@xerius/codey-style-vue2": "^1.0.0",
}

The version numbers of all packages was kept the same as before the -vue2 rename, and will continue to uphold the semver standard.

Documentation

The documentation for Vue 2 will not be published online. Most features will be directly ported to codey Vue 3 and this documentation will be updated accordingly.

If required, the Vue 2 documentation can be run locally by checking out the vue2 branch of the codey repository and running the following commands:

npm install
npm run app:docs

CDN Resources

The CDN resources for Vue 2 are available at the following location: https://cdn.xerius.be/vue2/

This folder contains the current available resources:

• style
• cookiebot
• hello-customer