pty-my-awesome-component
v0.2.0
Published
---
Downloads
15
Readme
Web Components Template
This is a web component template using Svelte, Storybook and Rollup.
Install
Generator
You can use create-webcomponent scaffolding CLI tool to create a brand new web component with Storybook, Jest boilerplates and built-in theming.
npx create-webcomponent
Note that you will need to have Node.js installed.
Get started
Install the dependencies...
npm install
...then start Storybook:
npm start
You should see your web component running in a Storybook test environment. It uses live-reload so all changes will be automatically reflected if any of the files in src
is updated.
Build
To create an optimised sharable version of the component:
npm run build
This will generate an optimised bundle into the dist
folder that can be loaded in the browser to register the web component.
Test
To test the code against our styleguides...
npm run lint
...then run the unit tests
npm test
Styleguide
The code styleguide is defined in .eslintrc
. It extends the wastly popular airbnb styleguide and forces all functions to be equipped with jsdoc annotations.
JSDoc Annotations
All functions / methods in the project must be annotated with valid jsdoc headers.
/**
* Adds the given parameters and returns the result.
* @memberOf my-component
* @param {number} a - first number to add
* @param {number} b - second number to add
* @returns {number}
* @example
* add(15, 20); // 35
*/
const add = (a, b) => {
return parseInt(a, 10) + parseInt(b, 10);
}
Snapshots
Jest utilizes the Storybook's storyshots integration to automatically generate snapshots. If you intentionally update the component and the snapshots do not match any longer you could ask Jest to regenerate the snapshots using the following command:
To regenerate the snapshots
npm test -- -u
Usage of the generated web component
<!-- From CDN -->
<script async type="module" src="your-cdn/my-component.js"></script>
<!-- From local installation -->
<script async type="module" src="/node_modules/my-component/dist/my-component.js"></script>
...
<body>
<my-component />
</body>
// as a common js module
import MyComponent from 'my-component';
Themes
In order to apply global styles on the web components you must place a <meta>
tag onto your HTML document containing a URL to your global stylesheet. The web component will pick this up and apply all these global styles into the ShadowDOM during the mounting phase.
<head>
<meta property="pty:themeURL" content="https://cdn.com/betonline.css" />
</head>
...
<body>
<my-component />
...
<script async type="module" src="https://cdn.com/my-component.js"></script>
</body>
Versioning
For transparency into our release cycle and in striving to maintain backward compatibility, this theme library is maintained under the Semantic Versioning guidelines.
Changelog
See the Releases section of our BitBucket project for changelogs.
References
Svelte Crush Course
https://www.youtube.com/watch?v=uK2RnIzrQ0M
Event Dispatching with Svelte
https://www.youtube.com/watch?v=9Bk7XFRMzgI
Custom Elements with Svelte
https://www.youtube.com/watch?v=p3u5rdJH9BM
Storybook
https://www.youtube.com/watch?v=p-LFh5Y89eM