Vouch UIKit

- Get Started
- Storybook
- Playroom
- Build package
- Test package locally with vouch-app-mono
- Testing published package
- Purge npm cache
- Purge specific bundles
- Releasing
- Update vouch-app
- Production release

Get Started

Ensure you have node 16 installed on your machine, for example via nvm, run nvm ls to check

``bash
nvm ls 16
`

you should see output if you have the version installed

`bash
-> v16.17.1
`

ensure you have git ssh setup locally before you clone the repo

`bash
git clone git@github.com:VouchAU/vouch-uikit-mono.git
`

install dependencies

`bash
cd vouch-uikit-mono
yarn
`

Storybook

https://uikit-storybook.vercel.app

Storybook is hosted on vercel and deployed automatically via GitHub Action every time changes are merged back to main. Storybook can also be deployed per PR by adding the deploy storybook label on the PR.

Local dev

`bash
yarn storybook
`

build storybook

`bash
yarn storybook:build
`

Playroom

https://uikit-playroom.vercel.app

Playroom is hosted on vercel and deployed automatically via GitHub Action every time changes are merged back to main. Playroom is not intended to be used on it's own because we don't get good autocomplete for web components, and playroom cannot render the svelte components natively.

Instead we have created a Playroom plugin for storybook that will automatically update the rendered web component when any of the story controls change.

Local dev

`bash
yarn playroom
`

build playroom

`bash
yarn playroom:build
`

Build package

Build src/lib production/beta/alpha package, make sure you change version in package.json.

`sh
cd packages/uikit
...
yarn package # production
`

Test package locally with vouch-app

Once you build the npm package, you can test locally with vouch-app to ensure everything works as expected before publishing to npm

Assuming you build a package according Build package, now you can create a symlink to your local package

`sh
cd package
yarn link
`

you should see this if successfully linked

`sh
yarn link v1.22.10
success Registered "@vouchfor/uikit".
info You can now run yarn link "@vouchfor/uikit" in the projects where you want to use this package and it will be used instead.
✨ Done in 0.04s.
`

go to vouch-app-mono folder and switch to the branch you want to test against with then link the local package

`sh
cd vouch-app-mono
git checkout VCH-222
yarn link @vouchfor/uikit
yarn dev
`

Voilà, you are testing your feature branch with the local uikit package and don't forget to roll back after testing

`sh
cd vouch-app
yarn unlink @vouchfor/uikit
...
cd vouch-uikit/package
yarn unlink
`

Test published package

You can publish an experimental version of the package by adding the publish rc label onto your PR. This will use the commit hash and a prerelease version number to publish onto NPM which you can then install into your application for testing.

This can be important because the published package and the linked package aren't necessarily 100% the same, some functionality is lost during the conversion to web-components:
- When using a svelte component within another svelte component, you are able to pass $$restProps down to inner DOM elements, this doesn't work when the svelte component is changed into a web-component during build time
- Using slots is a little weird
- When using normal svelte components, if you want to style slot contents from the parent component you need to use the :global() css selector
- This style is lost when compiling to web components, but can be regained by changing the :global() selector to a ::slotted() pseudo element

Purge jsdelivr cache

@vouchfor/uikit is most likely consumed by the latest tag, not version number to ensure clients can always get the latest updates. jsdelivr default has 7 days cache for tag, so we need to purge it to reflect new version number.

- Check current tag version number

- Click to check Production

- Purge cache
- _Danger_ Click to purge Production

$3

Our embed code snippet src attribute currently refers to a specific embed bundle js , for example

`html
type="module"
crossorigin="anonymous"
referrerpolicy="no-referrer"
src="https://cdn.jsdelivr.net/npm/@vouchfor/uikit@latest/embed/vouch-embed-inline-player.bundle.js"
>



`

In this case, you will need to purge the bundle file specifically by providing absolute path

`http
https://cdn.jsdelivr.net/npm/@vouchfor/uikit@{env}/embed/{filename}.bundle.js
https://cdn.jsdelivr.net/npm/@vouchfor/uikit@{env}/components/{filename}.bundle.js
`

for example,

`http
https://cdn.jsdelivr.net/npm/@vouchfor/uikit@latest/embed/vouch-embed-inline-player.bundle.js
`

Unit test

`bash
yarn test
`

update snapshot

`bash
yarn test -u
`

Releasing

To make sure we are delivering the highest quality software we can, there is a multi-step review and testing process before we go ahead with any release.

1. Once the feature has been implemented, create a PR and add the deploy storybook label to it, once storybook has been deployed send the link to the stakeholder that is in charge of the feature and get them to review.
- The deployment URL will be added as a comment to the PR once deployed
2. Use browserstack (credentials in 1password) to cross-browser test the storybook PR deployment using a wide range of operating systems and browser versions
- TODO: Figure out what is a reasonable set of browsers to test with
- TODO: Automated tools for cross browser testing using browserstack
3. Publish the package as a release candidate by adding the publish rc label to the PR
- Once published, install the package into the admin app and test the feature there to make sure your changes are working in situ.
- Create a PR deployment for the admin app using the release candidate package and get stakeholders to review also.
4. If there are no issues, bump the package to the appropriate version in the PR, then the PR can be merged into main and a regular release can be created using the instructions below
- TODO: Automate public release

Update vouch-app

@vouchfor/uikit is a dependency of the admin app within vouch-app-mono and vouch-app for embeds and the media player, follow the below steps to publish NPM package and update package.json dependency in vouch-app-mono.

> Always use semver for version numbering for main releases

- Major: Breaking changes
- Minor: Feature releases
- Patch: Hotfixes

Because we have a few different environments that the embeds may be fetching from (dev, staging and prod) we have added an env prop to all of the necessary embeds that allows you to choose the environment at run time. This, along with PR releases, removes the need for an alpha and beta package release and will allow us to better automate the release process.

$3

> You will need to log in vouch-tech on your terminal before publishing, credential is shared via 1Password.

`bash
npm login
`

1. Make sure you are in packages/uikit directory
2. Run yarn package
3. Move to the created package folder
4. Run npm publish --access public to publish under the latest tag

`bash
cd packages/uikit
yarn package
cd package
npm publish --access public
`

Then, using the same PR in vouch-app-mono` that you used to test the experimental version, bump to the now latest version and re-test one final time to make sure everything worked as expected.

If everything works correctly then the PR is ready to be merged, and the CDN cache can be purged to allow for upstream clients using embeds in their apps to receive the new version.

$3

Use this codepen to bump the package version that is downloaded from the CDN and make sure all of the embeds work as expected.