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

nvm ls 16

you should see output if you have the version installed

->     v16.17.1

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

git clone [email protected]:VouchAU/vouch-uikit-mono.git

install dependencies

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

yarn storybook

build storybook

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

yarn playroom

build playroom

yarn playroom:build

Build package

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

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

cd package
yarn link

you should see this if successfully linked

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

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

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(<selector>) css selector
  • This style is lost when compiling to web components, but can be regained by changing the :global(<selector>) selector to a ::slotted(<selector>) 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

Purge specific bundle.js

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

<script
  type="module"
  crossorigin="anonymous"
  referrerpolicy="no-referrer"
  src="https://cdn.jsdelivr.net/npm/@vouchfor/uikit@latest/embed/vouch-embed-inline-player.bundle.js"
></script>
<div>
  <vouch-embed-inline-player
    showname="true"
    showlogo="true"
    showcaption="true"
    showcontrol="true"
    autoplay="true"
    showwatermark="true"
    vouchid="u0Q37yiavT"
    apikey="6YoF1TdME4-DYRTycxZxr7LPSa1VYSz9MJj2ETOQUoOMt4zyLSrfJKSzBzerV"
    orientation="portrait"
  />
</div>

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

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,

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

Unit test

yarn test

update snapshot

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.

Prod release

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

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

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.

Post release testing

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