@vouchfor/uikit v0.0.0-experiment.6db4d4e

Vouch UIKit

• Get Started
  • Storybook
  • Build package
  • Test package locally with vouch-app
  • Publish to npm
  • Purge npm cache
• Update vouch-app
  • development
  • staging
  • production

Vouch UIKit consists of 2 libraries and 1 application

└── src
    ├── lib
    │    ├── components   # Design System Components (Web Component)
    │    │    ├── VouchBrandLogo.svelte
    │    │    ...
    │    │
    │    └── embed        # embed Components (Web Component)
    │    │    ├── VouchEmbedInlinePlayer.svelte
    │         ...
    │
    │
    ├── routes            # vouch public embed link (https://embed.vouchfor.com)
    │    ├── __layout.svelte
    │    ├── index.svelte
    │    ├── about.svelte
    │    ...
    │
    ├── app.css
    └── app.html

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 git@github.com: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 for three different build tags.

cd vouch-uikit
...
yarn package:alpha  # development
yarn package:beta   # staging
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 folder and switch to the branch you want to test against with then link the local package

cd vouch-app
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

Publish to npm

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

npm login
...

cd package
...
npm publish --access public --tag alpha  # development
npm publish --access public --tag beta   # staging
npm publish --access public              # production

Purge jsdelivr cache

@vouchfor/uikit is most likely consumed by tag, alpha, beta and latest, 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 Alpha
  • Click to check Beta
  • Click to check Production

• Purge cache

  • Click to purge Alpha
  • Click to purge Beta
  • 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@alpha/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@alpha/embed/vouch-embed-inline-player.bundle.js
https://cdn.jsdelivr.net/npm/@vouchfor/uikit@beta/embed/vouch-embed-inline-player.bundle.js
https://cdn.jsdelivr.net/npm/@vouchfor/uikit@latest/embed/vouch-embed-inline-player.bundle.js

Unit test

yarn test

update snapshot

yarn test -u

Update vouch-app

@vouchfor/uikit is a dependency of vouch-app for embeds and UI components, follow the below steps to publish NPM package and update package.json dependency in vouch-app.

Each PR should bump the minor version in package.json in order to push new version to NPM. e.g. "version": "3.9.0" in main branch, you should bump to "version": "3.10.0" in your branch.

The major version should only be used for releasing breaking changes. e.g. 3.0.0, 4.0.0

Development (dev.vouchfor.com)

Assuming your branch bumped version in package.json to

"version": "3.10.0"

Bump patch version number

Ensure your patch version number isn't used, e.g. if 3.10.0 was published before, bump to 3.10.1.

Build and publish

yarn package:alpha
cd package
npm publish --access public --tag alpha

Make sure you purge NPM CDN cache for package, see Purge npm cached tags

Update dependency in vouch-app

Ensure you already cloned vouch-app locally then switch to the folder.

cd vouch-app
git checkout development
git pull
git merge feature/VCH-111 # Optional, only when you have code change dependency in vouch-app as well
yarn upgrade @vouchfor/uikit@alpha

After upgrade, you should see version updates in both package.json and yarn.lock, but due to a known issue of yarn, please do these before committing changes

• Manually roll back package.json (should always "@vouchfor/uikit": "alpha" for development).
• run yarn again to update yarn.lock

git commit -m "Bumped uikit version"
git push

Staging (admin-staging.vouchfor.com)

Update staging environment is the same as Development but remember to change cmd to staging specific

yarn package:beta

npm publish --access public --tag beta

cd vouch-app
git checkout staging
git pull
git merge feature/VCH-111 # Optional, only when you have code change dependency in vouch-app as well
yarn upgrade @vouchfor/uikit@beta

Production (admin.vouchfor.com)

One thing different when release to production, since main branch can only be merged by PRs (after code review), so you will need to run yarn upgrade @vouchfor/uikit@latest under you feature branch and commit before merging the PR.

git checkout feature/VCH-111
yarn upgrade upgrade @vouchfor/uikit@latest
git commit -m "Bumped uikit version"
git push

When you run above cmd, your PR should be ready to merge (reviewed and QA tested)