🌐 common-lib-wc

A common library of web components using Vite, Svelte, Yarn and TypeScript that can be used by multiple teams for bridge, console and ModernOps applications.

This templates generates vanilla web components than can be used with plain HTML or within any major frameworks, such as React, Angular, Vue or Svelte (see compatibility).

Install

To install and build, run the following commands.

Note: The prefered means or installing and running is Yarn, but 'npm' can also be used.

clone [email protected]:bridge-console/common-wc-lib.git
cd common-wc-lib
yarn install

Library Structure

All the components source code lives in packages/lib folder. Only components with the .wc.svelte extension will be exported as web components and available in your library. This means that you can also use regular Svelte components with the .svelte extension as child components for your implementation details. Such child components are stored in the 'components' folder under 'lib'.

Adding Additional Web Components

You can add additional web components by adding them to the lib folder, with the the .wc.svelte extension and editing lib/index.js to export the new component.

Child Components

All other components that are not meant to be exposed as a web components should be placed under the 'components' folder. Normally, it's best to create a sub folder that represents the name of child component.

Each web component normally has two parts, the skeleton and the real component. In such case, both the skeleton and real component should be placed in same sub folder.

Running Test Harness

To allow validation of each web component a test harness is provider. To run harness, run.

yarn dev

Then open your browser to localhost:5173.

Modifying Test Harness

The source code for the test harness lives in packages/demo/ folder. Since the 'App.svelte' imports the lib directory, any web compoennt can be tested by just adding the web element used by the web component's tag; example 'data-table' here:

<svelte:options tag="data-table"/>

Of course other static data can be imported, etc. as needed.

Building Library of all Web Components

You can start a development server with:

yarn build

The command yarn build will create the web components library in the dist/lib/ folder. It creates both an ES module (dist/lib/common-wc-lib.js) suitable for bundler (non-minified), a minified ES module (dist/lib/common-wc-lib.min.js) and a regular UMD script (dist/lib/common-wc-lib.umd.js).

The build is automatically called when executing npm publish to distribute your library, thanks to the prepublishOnly script entry in package.json.

If you need unit tests, you can take a look at Jest and Jest testing library.

Building the library

The command yarn build will create the web components library in the dist/lib/ folder. It creates both an ES module (dist/lib/common-wc-lib.js) suitable for bundler (non-minified), a minified ES module (dist/lib/common-wc-lib.min.js) and a regular UMD script (dist/lib/common-wc-lib.umd.js).

The build is automatically called when executing npm publish to distribute your library, thanks to the prepublishOnly script entry in package.json.

Notes and limitations

This library does not provide any web components polyfills for older browsers support. It's usually best to leave that task to the host application, hence why they're left out.

Props

Any props accepted by your web component are automatically transformed to element attributes. Since camelCase or PascalCase does not work in HTML, you have to make sure to name your props in lowercase.

<script>
  export let myvalue = "Default";
</script>

However, only string attributes are supported. For more complex web component attributes, it is best to pass by use of an EventBus, which is how the console is passing data to the web components. For example, take a look at the DataTable web component.

// DataTable.wc.svelte
<script>
  onMount(() => {
    setShadowStyle("all.css");
    setShadowStyle("material-bare.css");
    window.EventBus.subscribe(('data-table-params'), (event) => {
      console.log('DataTable (params): ', event);
      if (event?.detail) {
        data = event.detail.data;
        error = event.detail.error;
        title = event.detail.title;
        columns = event.detail.columns;
        actions = event.detail.actions;
        actionUrl = event.detail.actionUrl;
        pageState = event.detail.pageState;
      }
    });
  });
</script>

Events

The Svelte syntax event for listening to events like on:myevent doesn't work with events dispatched from a Svelte web component (#3119).

You need to use a workaround for that, by creating a CustomEvent and dispatching it.

Here's an example:

// MyComponent.wc.svelte
<svelte:options tag="my-component" />
<script>
  import { get_current_component } from "svelte/internal";
  const component = get_current_component();
  
  // example function for dispatching events
  const dispatchEvent = (name, detail) =>
    component.dispatchEvent(new CustomEvent(name, { detail }));
</script>
<button on:click={() => dispatchEvent("test", "Hello!")}>
  Click to dispatch event
</button>

Why enable allowJs in the TS template?

While allowJs: false would indeed prevent the use of .js files in the project, it does not prevent the use of JavaScript syntax in .svelte files. In addition, it would force checkJs: false, bringing the worst of both worlds: not being able to guarantee the entire codebase is TypeScript, and also having worse typechecking for the existing JavaScript. In addition, there are valid use cases in which a mixed codebase may be relevant.

Why is HMR not preserving my local component state?

HMR state preservation comes with a number of gotchas! It has been disabled by default in both svelte-hmr and @sveltejs/vite-plugin-svelte due to its often surprising behavior. You can read the details here.

If you have state that's important to retain within a component, consider creating an external store which would not be replaced by HMR.

// store.ts
// An extremely simple external store
import { writable } from 'svelte/store'
export default writable(0)