npm package: @sendcloud/checkout-plugin-ui
Description: A package for rendering custom shipping options in a shop system during the checkout process
Latest version: 2.4.4

# Checkout plugin UI

A package for rendering custom shipping options in a shop system during the checkout process (e.g. service point picker, delivery date picker for nominated day delivery) or the Sendcloud platform.

## Links

- [npm package: @sendcloud/checkout-plugin-ui](https://npmjs.com/package/@sendcloud/checkout-plugin-ui)
- [Website: sendcloud.gitlab.io/frontend/checkout-plugin-ui](https://sendcloud.gitlab.io/frontend/checkout-plugin-ui/)
- [Technical specification: checkout plugin UI](https://sendcloud.atlassian.net/wiki/spaces/checkout/pages/429523024/Technical+specification+checkout+plugin+UI)

## Content

- [Documentation](#documentation)
- [Development](#development)
  - [Installing dependencies](#installing-dependencies)
  - [Starting a local development server](#starting-a-local-development-server)
  - [Running tests](#running-tests)
  - [Versioning](#versioning)
  - [Releasing a new package version](#releasing-a-new-package-version)
  - [Back-porting changes from the default branch into a pre-release branch](#back-porting-changes-from-the-default-branch-into-a-pre-release-branch)
  - [Verify browserslist configuration](#verify-browserslist-configuration)
  - [Project documentation](#project-documentation)

## Documentation

The project documentation is available at [sendcloud.gitlab.io/frontend/checkout-plugin-ui](https://sendcloud.gitlab.io/frontend/checkout-plugin-ui/).

## Development

**Important**: Before contributing to this project, one must read [Technical specification: checkout plugin UI](https://sendcloud.atlassian.net/wiki/spaces/checkout/pages/429523024/Technical+specification+checkout+plugin+UI). The checkout plugin UI package is implemented based on this specification. Significant changes made to the package must be documented in the technical specification. All releasing changes must be documented in the [changelog section](https://sendcloud.atlassian.net/wiki/spaces/checkout/pages/429523024/Technical+specification+checkout+plugin+UI#Changelog).

### Requirements

You must have [Node.js](https://nodejs.org/en) version 22.13.1 or above installed.

### Installing dependencies

```shell
npm install
```

### Starting a local development server

```shell
npm start
```

A local development server will be available at [localhost:3000/public](http://localhost:3000/public).

### Running tests

```shell
npm test
```

### Versioning

Read [Versioning](https://sendcloud.atlassian.net/wiki/spaces/Frontend/pages/838303756/npm+package+publishing#Versioning).

### Releasing a new package version

The general workflow is described in [Releasing a new package version](https://sendcloud.atlassian.net/wiki/spaces/Frontend/pages/838303756/npm+package+publishing#Releasing-a-new-package-version).

Specifically for the checkout-plugin-ui package, a few extra rules apply:

- Before releasing a new package version, the document docs/changelog.md needs to be manually updated.
- For breaking changes, a major package version must be released. Since the shop system plugins that use this package refer to it using minor version ranges (e.g. `@^1.0.0`), their implementation needs to be updated after a major version release (e.g. references to `@^1.0.0` need to be changed to `@^2.0.0`). Also, the “cache:purge” job in the .gitlab-ci.yml file needs to be updated accordingly.

### Back-porting changes from the default branch into a pre-release branch

Read [Keeping pre-release branches up-to-date with a project’s default branch](https://sendcloud.atlassian.net/wiki/spaces/Frontend/pages/838303756/npm+package+publishing#Keeping-pre-release-branches-up-to-date-with-a-project%E2%80%99s-default-branch).

### Verify browserslist configuration

Open the babel.config.js file and copy the value of the `targets` configuration and run `npx browserslist $targets` like this:

```shell
npx browserslist '> 1% in my stats and not ie <= 11'
```

This will result in an output like this:

```text
and_chr 89
android 81
chrome 88
chrome 87
chrome 86
chrome 85
chrome 84
chrome 83
chrome 81
chrome 80
edge 85
edge 84
edge 18
firefox 86
firefox 85
firefox 84
firefox 83
firefox 82
firefox 81
firefox 80
firefox 79
firefox 78
firefox 77
firefox 76
```

### Project documentation

All project documentation can be found under the `docs/` directory. Make sure to update related documentation whenever possible. All documentation is published using [Gitlab pages](https://docs.gitlab.com/ee/user/project/pages/). You can preview a merge request’s changes to the documentation website using GitLab review environments. Wait for the MR’s CI pipeline to complete and click the “Deploy” button:

![Review environment image](.assets/review-environments.png)

**Note**: The _View latest app_ action will point to an older version of the deployed documentation for a particular merge request. In the example above, new changes were introduced in the merge request and not deployed yet.

### Setting the `type` field to module in package.json

(Last updated/checked: 2021-12-01)

Currently, this package doesn’t include `"type": "module",` in its package.json file. Setting it marks the package as a true ES module package. However, this cannot currently be done because Jest isn’t ready for it. Following <https://jestjs.io/docs/ecmascript-modules> leads to the following, unexpected issues:

- [has no workaround] <https://github.com/facebook/jest/issues/12145>: Mocking the implementation of a function `fn` that is imported into the test via `import * as alias from './module.js` leads to the error “TypeError: Cannot assign to read only property 'fn' of object '[object Module]'”.
- [has workaround] <https://github.com/facebook/jest/issues/10025>: Mocking the implementation of an entire module using `jest.doMock` breaks completely. To mock a native ES module, a new `mockModule` function is to be introduced that will solve this issue. For now `jest.unstable_mockModule` will do the job.