@vouchfor/uikit
v7.5.0
Published
Vouch Svelte UIKit
Downloads
810
Readme
Vouch UIKit
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
- When using normal svelte components, if you want to style slot contents from the parent component you need to use the
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
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.
- 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
- 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
- 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.
- 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
- Make sure you are in
packages/uikit
directory - Run
yarn package
- Move to the created
package
folder - Run
npm publish --access public
to publish under thelatest
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.