DEV Community: Thomas Allmer

Introducing check html links - no more bad links

Thomas Allmer — Wed, 27 Jan 2021 11:59:33 +0000

TL;DR : I created a standalone tool that can help you fix all the broken links in your websites/documentation. You can check it out on npm as check-html-links

In my developer career, I have put live multiple websites and honestly often within a few days, there was always this one issue raised. "This link on xxx is broken". 🤦‍♂️

Often these things happen as somewhere a page got moved or renamed and not every location got updated.
It's really hard to catch especially if you have a dynamic page like with WordPress or an SPA. And for users, there is nothing worse than landing on your documentation only to find a 404 staring back at them.

Luckily, with the rise of SSG (Static Site Generators), this problem becomes easier to tackle and can be solved in large part. The reason for that is that with all HTML rendered upfront as static files we can read all of them and check every link.

Evaluation and the decision for a new tool

Of course, I am not the first one to come up with that idea and there are multiple tools available on the market already.
However, when checking existing solutions I found out that most of them didn't satisfy me in at least on way 😅. Things I noticed: slow to execute, deprecated, large dependency tree, confusing output for the user, ...

Reviewing these tools I decided to create my own, with the following requirements :

Blazing fast
User-focused output
Few dependencies, to keep it lean
Preferably in the NodeJS ecosystem

Focusing on Useful Output

Most tools evaluated check files individually and report on their findings individually. That means if you have a broken link in your header or footer, you will get one line (or even multiple lines) of an error message(s) for EVERY page.

I tested this on the 11ty-website and there are currently 516 broken links in 501 files. However, the source of those 516 broken links is just 13 missing pages/resources.

In my implementation, I decided to switch from an "Error in File Focused" method to a "Missing File Focused". Let's see this with examples

Error in File Focused

This is what a lot of current existing solutions implement. Here is part of the output that is being produced:

[...]
authors/ryzokuken/index.html
  target does not exist --- authors/ryzokuken/index.html --> /speedlify/
authors/alex_kaul/index.html
  target does not exist --- authors/alex_kaul/index.html --> /speedlify/
docs/config/index.html
  target does not exist --- docs/config/index.html --> /speedlify/
  hash does not exist --- docs/config/index.html --> /docs/copy/#disabling-passthrough-file-copy
authors/cramforce/index.html
  target does not exist --- authors/cramforce/index.html --> /speedlify/
authors/accudio/index.html
  target does not exist --- authors/accudio/index.html --> /speedlify/
[...]

We get ~2000 lines of errors for /speedlify/ as it's not found ~500 times. In the middle of those errors, we also see some other broken links.
Because the reporting is focusing first on the files, and then on the actual error it is difficult to know where most errors originate from.

Missing File Focused

Let us turn that around and focus on missing references indeed. Here is the output for the same input website :

[...]
  1. missing reference target _site/speedlify/index.html
    from _site/404.html:1942:13 via href="/speedlify/"
    from _site/authors/_amorgunov/index.html:2031:13 via href="/speedlify/"
    from _site/authors/_coolcut/index.html:2031:13 via href="/speedlify/"
    ... 495 more references to this target

  2. missing id="disabling-passthrough-file-copy" in _site/docs/copy/index.html
    from _site/docs/config/index.html:2527:267 via href="/docs/copy/#disabling-passthrough-file-copy"

  3. missing reference target _site/authors/dkruythoff/github.com/dkruythoff/darius-codes
    from _site/authors/dkruythoff/index.html:2102:234 via href="github.com/dkruythoff/darius-codes"
[...]

We get one 5 line error for /speedlify/ and it tells us it's missing 495 times + 3 examples usages.
Afterward, we find very clearly more missing references and where they occurred.

A clear winner

Comparing those two outputs makes it pretty clear to me that Missing File Focused will make more sense if there is a chance that some links will be broken everywhere. My implementation focuses on missing links in its output. This is crucial because it allows developers to know where to focus their efforts first to get the biggest wins.

Focusing on Speed

Speed is always nice to have but in this case, it's probably vital. I need this to be fast so that I can run it potentially on every save. Speed is also very important in case the tool runs in a CI for example. For projects with extensive documentation, we don't want to hog the CI only to check for documentation.

Luckily HTML is an awesome language to analyze as it's declarative, which means you can read and analyze it at the same time. This may even mean that the HTML is already processed by the time the file is done reading.

With this knowledge I was hopeful - but reality didn't deliver 😅. The only tool that could keep up with the speed I needed was implemented in Go.

It seems that most tools use sophisticated parsers meant to create full syntax trees of your HTML.
In reality for link checking all you need to know are the id and the href attributes.

I have been using sax-wasm in a few situations before and I knew it supported streaming. I knew that way it could be FAST 🤞!

How fast are we talking about though?

As a rule of thumb, I decided that the analysis should be finished within 1s for a small site (up to 200 pages).
The main reason is already listed above: To not disturb during writing/development as it will run on every save.
For medium sites (200 - 1000 pages), it's reasonable if it takes a little longer - let's aim for less than 5 seconds. This will probably be a breaking point where you execute it only on-demand and in the CI instead of executing it on every save.

Results are gatherd on January 26, 2021:

Website	Pages	Duration
open-wc.org	90	~0.4s
11ty.dev	501	~2.5s
web.dev	830	~3.7s
eslint.org	3475	~12.4s

Being part of the NodeJS ecosystem

My daily workflow is hugely dominated by JavaScript, so it was only natural to want to stay in the same environment if I could reach my earlier requirements with it.
On top of this, the end goal is to integrate it within a bigger WIP system called Rocket which is node-based so therefore it will need to at least support NodeJS. Having it standalone (usable via npx) also makes it more versatile and easier to maintain/test.

Focusing on a small Dependency Tree

The JavaScript and NodeJs ecosystem is very active and constantly shifting. Lots of changes/improvements happen all the time. It's often hard to keep up. Therefore having a small dependency tree is something to always thrive for because it will reduce the maintenance burden down the line. And as an added benefit, it makes it smaller and easily embeddable as less stuff has to go down the wire. Lean is king 👑.

Solution

As already mentioned I went on and implement a link checker myself 😅. So far it fits all my requirements so I call it a success 🎉! You can find it on npm.

I called it check-html-links and its slogan is "no more broken links or assets".

The features so far are:

extracts every attribute value of id, href, src, srset
use a wasm parser (sax-wasm)
streams the html for performance
check if file or id within file exist
focus on missing references/sources

Usage

It does check your final html output so you need to execute it after your Static Site Generator.

npx check-html-links _site

Usage Github Action

Julien created a Github action available for the tool, so you can easily plug it in your existing CI. You can find it on the GitHub Marketplace.

Here is a complete example workflow that will check the result of the folder _site in the root of your repository on each push:

on: [push]

jobs:
  check_html_links_job:
    runs-on: ubuntu-latest
    name: A job to test check-html-links-action
    steps:
      - uses: actions/checkout@v2
      - name: check-html-links-action step
        id: check-links
        uses: modernweb-dev/check-html-links-action@v1
        with:
          doc-folder: '_site_'

Comparison

Checking the output of 11ty-website with 13 missing reference targets (used by 516 links) while checking 501 files. (on January 17, 2021)

Tool	Lines printed	Duration	Lang	Dependency Tree
check-html-links	38	~2.5s	node	19
link-checker	3000+	~11s	node	106
hyperlink	68	4m 20s	node	481
htmltest	1000+	~0.7s	GO	-

Future

The basic functionality is finished and it's reasonabley fast.

Topic to work on:

Allow to ignore folders (potentially via a cli parameter)
Support for <base href="/">
Big Sites Speed improvements (potentially running multiple parsers in parallel for 1000+ pages)
Speed improvements by introducing a "permanent cache" for the parse result (if file did not change, parse result will not change - we still check all links)
Memory consumption check (see if there is room for improvements)
Improve node api
Check external links

Acknowledgements

Thank you for following along on my journey on creating check-html-links. You can find the code on Github.

Thanks to Julien for feedback and helping turn my scribbles to a followable story.

If you think my open source work is valuable then I would like you to check out my personal Github Sponsor Page. Or you can support our whole group via the Modern Web Open Collective.

Photo by Teslariu Mihai on Unsplash

Introducing mdjs - interactive demos everywhere

Thomas Allmer — Wed, 15 Apr 2020 12:26:09 +0000

All shared code should have written documentation to show what it can be used for and what the idea behind it is.
Users should at least be able to get a high level understanding of what they are using, what they're using it for, and why.

On the web, we have many many different ways of writing documentation.
However, one thing almost all of them have in common is that they rely on Markdown or some kind of variation of it.

And it's no surprise, because Markdown is supported practically everywhere (vscode, atom, github, gitlab, dev.to, npmjs, ...)

For tools that do not run in the browser

In this case, you will mostly share code snippets that people will need to run in their own projects in which case traditional static site generators like Docusaurus, VuePress, Gatsby, et al work great. All of them have full support for Markdown and allow you to easily create beautiful documentation pages with code snippets/highlighting, and more.

And frankly, if that is your use case almost everything you need should be possible with those tools as long as you feel comfortable with the ecosystem/framework.

For (visual) components that do run in the browser

In this context, users probably do expect a live demo to see all the different options of your component in action. So pure Markdown is usually not enough as we now want to actually execute code and "insert" our working component in our documentation somehow. This would require specialized handling for each framework.

Vue

For Vue, as an example, you can use VuePress which auto registers all Vue components in a certain folder and then you can use as normal html tags since Markdown supports html

.
└─ .vuepress
  └─ components
      ├─ demo-1.vue

<demo-1 />

supports vue components and has "magical" import for them
no support for generic javascript or passing properties to components

React

For React you can use Mdx which extends Markdown with JSX support. Mdx is available via multiple tools like Gatsby, docz, storybook, etc.

import { Chart } from '../components/chart'

# Here’s a chart

The chart is rendered inside our MDX document.
<Chart />

supports import/export JavaScript
passes everything through JSX
Doesn't look great on github, requires special tools in editors to get highlighting

Limitations

What all these specialized tools have in common is that they require a specific build tooling setup to work.
For web components, none of that is actually needed. Markdown already allows for HTML. The only missing piece is how to load a web component through JavaScript?

Introducing Markdown with JavaScript (mdjs)

The primary goals are

minimal complexity
follows progressive enhancement
stick close to valid markdown syntax
code highlighting in editors without additional tools
looks good on github/gitlab/any source code management tool

The fundamental idea seems almost too simple to be true. We "enhance" a code fence block with additional meta data js script.

```js script
import './my-component.js';
```

# This is my component
<my-component></my-component>

And that's it! 😄

Alright, enough talk, you can see it live here:

==> Link to editable demo <==

How does it work

Mdjs hooks into remark and extracts all those tagged js blocks.
In the end, html and js is separately available.

{
  html: '<h1>This is my component</h1><my-component></my-component>',
  jsCode: "import './my-component.js';"
}

It can then be combined/processed by any tool to create an actual documentation page.

The process looks like this:

Extract js script and separate it from md
Render md
Provide html & js

Link to animation as slides

This already is powerful enough to directly include JavaScript and render web components with attributes.

Enhancing mdjs with demo format

Now that we can execute JavaScript within our Markdown this opens the door for more advanced features.

Our first step is to create another enhanced js code block, namely; js story.
From this code block you can export a function to be executed on demand:

```js script
import './my-component.js';
```

# This is my component

```js preview-story
export const demo = () => `<my-component header="from attribute"></my-component>`
```

if you want to add a border around and a button to show/hide the actual source code you can use js preview-story

What you get looks something like this

{
  html: '<h1>This is my component</h1><my-component></my-component>',
  jsCode: "import './my-component.js';",
  stories: [
    key: 'demo',
    name: 'demo',
    code: 'export const demo = () => `<my-component header="from attribute"></my-component>`',
  ]
}

Under the hood, this adds an extra step to the processing:

Extract js script and separate from md
Extract js story and js preview-story and separate from md
Put a placeholder <mdjs-story mdjs-story-name="demo"></mdjs-story> or mdjs-preview at it's place
Render markdown
Provide html, javascript, and stories

This is all the information we need to create full javascript and demo capable pages purely from markdown.

By default Mdjs takes it a small step further by supporting an actual template system - namely lit-html.

```js script
import './demo-wc-card.js';
import { html } from 'lit-html';
```

# This is my component

```js story
export const demo = () => html`
  <demo-wc-card header="HEADER"></demo-wc-card>
`;
```

Link to animation as slides

Here another playground mimicking a full documentation page.

==> Link to editable demo <==

mdjs default docs page

Once all this meta-information is available you can render a specific docs page.

It basically comes down to generating this code which assigns the demo function to the actual web component.

const stories = [{ key: 'demo', story: demo, code: demo }];
for (const story of stories) {
  const storyEl = rootNode.querySelector(`[mdjs-story-name="${story.key}"]`);
  storyEl.story = story.story;
  storyEl.code = story.code;
}

All of this happens under the hood for you 🤗

Where can you use mdjs?

You can use it locally via es-dev-server

Here i'll show you how you can create a github like markdown view for all your local markdown files including live demos.

Install es-dev-server as a dependency by running npm i -D es-dev-server
Add the following script to your package.json:

  "scripts": {
    "start": "es-dev-server",
  }

Create a es-dev-server.config.js in the root of your repo.

  const { mdjsTransformer } = require('@mdjs/core');

  module.exports = {
    nodeResolve: true,
    open: 'README.md',
    watch: true,
    responseTransformers: [mdjsTransformer],
  };

After executing npm run start you can happily browse your live documentation via http://localhost:8000/README.md.

You can see an example setup in the demo-wc-card repo.

You can use it via Storybook

If you want to work on individual components or get a list of all demos you can use Storybook.

Install dependency npm i -D @open-wc/demoing-storybook
Add to your package.json:

  "scripts": {
    "storybook": "start-storybook",
  }

Adjust your .storybook/main.js to load markdown files

  module.exports = {
    stories: ['../README.md', '../docs/**/*.md'],
    esDevServer: {
      nodeResolve: true,
      watch: true,
      open: true,
    },
  };

Add to every markdown file that should be in storybook a name via

  export default {
    title: 'My Group/My Awesome Component',
  };

And just like that, you are good to go.
No additional changes to any files are needed; a plugin will take care of everything by converting your markdown files to the support Storybook's mdx format.

For more detailed information please see https://open-wc.org/demoing-storybook/.

Show it on github

Since Github supports markdown out of the box, we can take things even further by using Mdjs.

As it's not supported by github directly you will need a chrome extension called mdjs-viewer.

Do you want to see a demo without opening a different page? mdjs-viewer!
Do you want to show a live example of the issue you are having? mdjs-viewer!

Almost looks like black magic, huh?
All you did was install a Chrome extension and suddenly Github got superpowers.

All that you need is to have some Markdown files with the correct code fence blocks, and have your code up and running on unpkg.com.

How does it actually work?

The extension detects which Github page you are on.
If it actually finds a markdown file or an issue with mdjs code then it adds a "show demo" button to activate it.
Only if you click the button it will start gathering all the needed info.

find the nearest package.json
read the actual markdown file/issue content
replace all bare import with unpkg.com imports
replace all relative imports with unpkg.com and the name of the package.json + relative path for it
create a secured iframe
position the iframe absolute as an overlays
put the javascript and html code inside the iframe
the button becomes a toggle to show/hide the iframe

Some of the tasks are more complicated and require some extra work to make it secure but in essence, that's it.

With that, you can put documentation with live examples on github.
Even issues with demos showing the actual error in the code are possible.

That sure sounds like a hell of a tool to improve your documentation an issue reproduction, doesn't it?
Especially as the readme and issue content still remain useful even without the extension.

For more detailed information please see https://github.com/open-wc/mdjs-viewer.

Supported on webcomponents.dev

Fully supported by this awesome online editor.

You can directly edit your documentation, demos and code directly in the browser.

You can start directly with documentation as in the screenshot above, or even better you can use it in every Markdown file or README.md 💪

Give it a go and document your components in all its glory.

All the demo links are actually from webcomponents.dev.

Be sure to check it out.

How you can add support for mdjs

Please check the official documentation page at https://rocket.modern-web.dev/docs/markdown-javascript/overview/.

Resume

There you have it - mdjs is a format that can be shown in many different ways.
It is your single source of truth for good looking documentation everywhere.
Be it locally, a published storybook, on github or npmjs it always looks good even if there is no direct support for it, but when possible it will become interactive demos through progressive enhancement.

Now go out there and write good documentation for your components!

Future

Have a separate github repo (potentially group as well).
Have a dedicated homepage
The default story preview frame should look a little nicer
Support multiple renderers - discussion in issue
Highlighting of code snippets
More helpers to be used within stories
... (feel free to open issues within the corresponding projects)

Acknowledgements

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Pascal for feedback and helping turn my scribbles to a followable story.

Photo by Aaron Burden on Unsplash

Using JavaScript Mixins The Good Parts

Thomas Allmer — Tue, 18 Feb 2020 12:12:50 +0000

Before we can start using something we need to understand what it is and what we can achieve with it.

What is a Mixin?

A mixin is an abstract subclass; i.e. a subclass definition that may be applied to different superclasses to create a related family of modified classes.

Gilad Bracha and William Cook, Mixin-based Inheritance

Let's take for example Logging. Imagine you have 3 Pages

Red
Green
Blue

              +----------+
              |   Page   |
              +----------+
                |  |  |
     +----------+  |  +-----------+
     |             |              |
+---------+ +-----------+ +----------+
| PageRed | | PageGreen | | PageBlue |
+----+----+ +-----------+ +----------+

class Page {}
class PageRed extends Page {}
class PageGreen extends Page {}
class PageBlue extends Page {}

Now we want to log whenever someone goes on Page Red.
To achieve that we extend Page Red and make a Logged Page Red.

              +----------+
              |   Page   |
              +-+--+--+--+
                |  |  |
     +----------+  |  +-----------+
     |             |              |
+----+----+  +-----+-----+  +-----+----+
| PageRed |  | PageGreen |  | PageBlue |
+----+----+  +-----------+  +----------+
     |
+----+----+
| Logged  |
| PageRed |
+---------+

class Page {}
class PageRed extends Page {}
class PageGreen extends Page {}
class PageBlue extends Page {}
class LoggedPagRed extends PageRed {}

If we want to start logging for PageGreen we have an issue:

we can't put the logic in Page as Blue should not be logged
we can't reuse the logic in Logged PageGreen as we can not extend from 2 sources (even if we could it would mean conflicting info in Red and Green)

What we can do is put it in an "external" place and write it so it can be "mixed in".

               +----------+                +----------+
               |   Page   |                | Logging* |
               +-+--+--+--+                +----------+
                 |  |  |
      +----------+  |  +-----------+
      |             |              |
+-----+----+  +-----+-----+  +-----+----+
| PageRed  |  | PageGreen |  | PageBlue |
|  with    |  |   with    |  +----------+
| Logging* |  |  Logging* |
+----------+  +-----------+

// defining the Mixin
export const LoggingMixin = superclass =>
  class LoggingMixin extends superclass {
    // logging logic
  };

class Page {}
// applying a Mixin
class PageRed extends LoggingMixin(Page) {}
class PageGreen extends LoggingMixin(Page) {}
class PageBlue extends Page {}

With that approach we can extract logic into a separate code piece we can use where needed.

For a more in-depth technical explanation please read Real Mixins with JavaScript Classes.

Why is Deduping of Mixins Necessary?

We now want all logging to the Red, Green, and Blue pages.
Easy enough - as we can now apply the LoggingMixin on the Page itself.

               +----------+               +----------+
               |   Page   |               | Logging* |
               |   with   |               +----------+
               | Logging* |
               +-+--+--+--+
                 |  |  |
      +----------+  |  +-----------+
      |             |              |
+-----+----+  +-----+-----+  +-----+----+
| PageRed  |  | PageGreen |  | PageBlue |
+----------+  |   with    |  +----------+
              |  Logging* |
              +-----------+

However, Team Green was eager to launch, so they already applied LoggingMixin to their Page class. When we apply it to the base Page class, Mixin is now applied twice 😱
Suddenly, the Green page will print each log twice - not what we originally had in mind.

What we need to do is make sure that each Mixin is attached only once even if we try to apply it multiple times.

Generally, the more generic a mixin is, the higher the chance becomes that is gets applied more than once. As a mixin author, you can't control how it is used, and can't always predict it. So as a safety measure it is always recommended to create deduping mixins.

npm i @open-wc/dedupe-mixin

import { dedupeMixin } from '@open-wc/dedupe-mixin';

export const MyMixin = dedupeMixin(
  superclass =>
    class MyMixin extends superclass {
      // your mixin code goes here
    },
);

You can see exactly this situation in the demo.

By applying dedupeMixin to the mixin function, before we export it, we can be sure that our mixin class will only take effect once, even if it is mixed into multiple base classes in the inheritance chain.

no-dedupe "fails" by logging Green two times
with-dedupe "succeeds" by logging Green one time as well

You can check the source code for both on github.

Nested examples

You may think that the above example is too simple and can be solved by aligning on when to do changes.
However, in most real-life scenarios the situation is much more complicated 🙈
Mixins can be extended and just because you import a class it does not mean that this class has some Mixins pre-applied.

Consider this example:

               +----------+               +----------+      +----------+
               |   Page   |               | Logging* |      | Feature  |
               |   with   |               +----+-----+      |   with   |
               | Logging* |                    |            | Metrics* |
               +-+--+--+--+               +----+-----+      +----+--+--+
                 |  |  |                  | Metrics* |           |  |
      +----------+  |  +-----------+      +----------+           |  +------
      |             |              |                             |
+-----+----+  +-----+-----+  +-----+----+                 +------+-------+
| PageRed  |  | PageGreen |  | PageBlue |                 | WaterFeature |
+----------+  +-----------+  |   with   |                 +--------------+
                             | Metrics* |
                             +----------+

Pages generally only need Logging
There is however also more advanced Metrics System which extends Logging
Metrics was separately developed for Features
When we now want to get the same Metrics on Page Blue we get duplicate logging without consciously applying logging even once (we do class PageBlue extends MetricsMixin(Page) {})
Only deduping can help in these scenarios

When NOT to use a Mixin

You may think now "dam that is powerful" and you are right. Should we use it now for everything? Hell, no.

Only use it if you absolutely need access to the instance itself. Here are some bad examples when NOT to use a Mixin.

I want to do `if (this.isIE11()) { // ... }`

For any "pure" function it is better to keep it outside of the class/prototype. e.g. better write it like so

import { isIE11 } from './helpers.js';

if (isIE11()) {}

I want to have a special `this.addEventListener()`

Firstly overriding built-in functions can be really dangerous. When inside your class and when you need to make a very specific use-case happen then it might be ok. However, if that magically happens while using a Mixin it can be very confusing.

Better to have these as an extra function which can pass on this. That way people can opt these special features without "polluting" their prototype chain.

import { specialAddEventListener } from './helpers.js';

specialAddEventListener(this, 'click', () => console.log('clicked'));

Secondly all properties/methods are global to the class/prototype. That means if two mixins use the same name it will clash. Therefore make sure to definitely use specific names for private/protected methods and make sure if you use common names that it is clear from the mixin name/docs.

When to use a Mixin

If you need to have access to the class instance itself. Meaning if every instance may have a different setting.

A valid example could be for example a LocalizeMixin which enables you to set myEl.locale = 'de-DE';. In this case, the Mixin needs to provide and react to this property.

import { dedupeMixin } from '@open-wc/dedupe-mixin';

export const LocalizeMixin = dedupeMixin(
  superclass =>
    class LocalizeMixin extends superclass {
      // this assumes a Mixin for LitElement
      static get properties() {
        return {
          locale: { type: String }
        };
      }

      updated(changedProperties) {
        super.updated(changedProperties);
        if (changedProperties.has('locale')) {
          // react to locale change
        }
      }
    },
);

What we have learned

With Mixins you can bring shared logic into multiple classes. It is a very powerful tool - and with that power comes responsibility. Be sure to use it responsibly and to dedupe your mixins.

Notes

Ascii Graphics made with AsciiFlow
Photo by Vania Shows on Unsplash

ING open sources Lion: A library of performant, accessible & flexible Web Components

Thomas Allmer — Thu, 13 Feb 2020 11:19:17 +0000

Originally posted on the ING tech blog.

TL;DR: Web development can be hard, whether you're making your own components, implementing Design Systems, support many different browsers, incorporating accessibility, or adding third party dependencies. Lion aims to make your life a little bit easier, by taking the groundwork of feature complete, accessible, performant, and framework agnostic components out of your hands! Check out the repo at ing-bank/lion.

As some of you may already know, ING has a long and rich history of building Web Components, starting out with the Polymer library, all the way up to the recently released LitElement.

Need a refresher? Web Components are a set of browser standards that allow us to write browser native, reusable, encapsulated, and modular components.

Web Components standards have finally matured, and today, there are many ways to build and consume your Web Components, like: Angular Elements, Stencil, Vue, Svelte and many, many more. And with the release of the new Chromium Edge, this means that all major browsers support Web Components natively.

So today, I'm happy to share with you all that ING is open-sourcing its own core library of Web Components: Lion! 🎉

Why Lion?

Imagine the following fictional scenario:

Lea is a developer who works at Betatech, and is working on a new in-house application.

Framework Agnostic

Finding components is hard, and can lead to a lot of frustration.

Lea finds a perfect component for her use case, but unfortunately, it's written in a specific JavaScript framework, and Betatech uses a different framework, so sadly she's not able to use it.

Additionally, companies have their own visual identities and overriding fully styled components to make them look like the companies identity, can sometimes be more work than start styling from scratch.

Lea finds a component that offers all the needed functionalities, however, it looks vastly different from Betatechs identity.

Customize Functionality

Once you've found your perfect component, at some point down the line you may discover that the component lacks some kind of functionality that you would like to achieve.

Lea decides to copy over the code of a component she found, and implement the feature herself, and as a result now has to maintain the entire component as well, which becomes an added burden to the project.

Accessibility

Your components should be usable by every kind of user. Accessibility is hard to get right, but an essential feature, additionally, accessibility issues can be impossible to fix at a later stage without breaking changes, so it is crucial to incorporate accessibility right from the start.

Somewhere down the line, Lea finds an accessibility issue with a component she found online. she can't fix this issue in her code, so she asks the maintainers to help her out. They tell her they can't fix it because they don't want to do a breaking change.

Or, alternatively

Lea writes her own component, and the accessibility issue is hard to fix because of the way she initially wrote her HTML structure, and will also lead to a breaking change.

Summary

Does Lea's story feel relatable?

It highlights multiple common issues in modern web development:

Finding and adding a dependency is a big deal
Picking something because of looks alone might not always be the best choice
Adjusting behavior or styling can be tough to maintain
If a package is popular it doesn't mean it has good accessibility or performance

What can we do to tackle these issues?

🤔 Imagine having components that purely focus on functionality, and leave the design up to you
🤔 Imagine that these components come with great accessibility and performance
🤔 Imagine these components are highly extendable and flexible

Now stop imagining, and look at Lion 🦁

What is Lion?

We want to bring the web forward - one component at a time.

Lion is a white-label, open-source, framework-agnostic component library, and can be the foundation for your codified in-house Design System. Aligning on design and usability is already a tough challenge, with Lion, we hope to take some of the work out of your hands.

White Label

Lion is a core package of white label Web Components. What this means is that the core components only consist of very minimal styling, yet has all the fundamental functionalities. White label products are often created so others can easily rebrand them with their own visual identity. This is great because it means that everyone can use the core functionalities of our components while bringing their own branding or Design System because surprisingly, not everyone loves orange.

And this is exactly what we at ING do as well. Our very own ing-web components extend the Lion components and apply our own ING visual identity which mostly is a thin layer on top of Lion.

Check out the Lion demo's. Looks plain, doesn't it? And now compare Lion to ing-web:

🎯 Focus

Lion was designed with a focus on global usage and reusability in mind. And as such, the following features were incorporated right from the start:

♻️ Reusability - Our components are meant to be distributed and used on a global scale
🚹 Accessibility - Our components are meant to be accessible for everyone
🚀 Performance - Our components are meant to be small, performant and fast

These features allow us to roll out our components globally and have a single point of truth. It ensures that everyone in ING has a solid set of building blocks to build their application with, and get up and running in no time.

Lessons learned

ING started using web components very early on, and Lion is not the first component library we built. So you may wonder, how are these components different from the previous generation?

Lion is built from the ground up to allow for accessibility and extendability as we learned that these things are almost impossible to change/achieve at a later point in development. We'd like to highlight a few of the lessons learned while making Lion:

Not everything has to be a Web Component, for certain functionality regular JavaScript is better.
Stay as close to native semantic HTML elements as possible.
Incorporate accessibility from the start.
Not everything needs to be in the shadow DOM, this is especially important for aria relations and accessibility.
UI components are hard

Everyone should use web components but not everyone should write them

- Erik Kroes

🙋‍ Join us!

Adopt Lion!

Lion can help you implement your Design System by providing a white-label, functional, accessible and performant foundation for your component library. All you need to do is bring your own design! So if your company is looking to codify your Design System, Lion makes a great base to start from.

Alternatively, you could use Lion to create a web component version of your favorite design systems, such as: Bulma, Bootstrap, Material, Bolt, Argon, Tailwind.

Additionally, the more users and contributors Lion has, the more stable the Lion base will become, which helps everyone who uses Lion.

Contribute to Lion!

At the time of writing, Lion is still in beta phase. We'd love to have your feedback before going to a stable release, so: Do you like open source, and do you want to help Lion out?
You can do so by:

Reporting/fixing issues
Working on a completely new component (start with an issue for discussion first)
Improving documentation
... every contribution counts! Even typo fixes in the docs 🤓

Feel free to create a github issue for any feedback or questions you might have.
You can also find us on the Polymer slack in the #lion channel.

You can join the Polymer slack by visiting https://www.polymer-project.org/slack-invite.

🔨 Extend the components

You can use Lion as the base to implement your own codified Design System.

Let see how Lea's story would have panned out if she would have chosen Lion instead.

First, install what you need

npm i lit-element @lion/tabs

Create a lea-tabs component by reusing the functionality of Lion. This gives Lea all the functionality and accessible core that she needs for her custom tabs component.

import { css } from 'lit-element';
import { LionTabs } from '@lion/tabs';

export class LeaTabs extends LionTabs {
  static get styles() {
    return [
      super.styles,
      css`
        /* my stylings */
      `
    ];
  }

  connectedCallback() {
    super.connectedCallback();
    this._setupFeature();
  }

  _setupFeature() {
    // being awesome
  }
}

customElements.define('lea-tabs', LeaTabs);

Lea also wants to be able to style the tab and tab-panel according to Betatechs visual identity. In order to do so, she creates a lea-tab-panel component and a lea-tab component, which she can then fully style however she desires, and eventually place inside the lea-tabs component. You can see how Lea achieved this in the example down below.

import { LitElement, html, css } from 'lit-element';

export class LeaTab extends LitElement {
  static get styles() {
    return css`/* my stylings */`;
  }

  render() {
    return html`
      <!-- dom as needed -->
      <slot></slot>
    `;
  }
}

customElements.define('lea-tab', LeaTab);

Excellent! Lea can now use the tabs component like so:

<lea-tabs>
  <lea-tab slot="tab">Info</lea-tab>
  <lea-tab-panel slot="panel">
    Info page with lots of information about us.
  </lea-tab-panel>
  <lea-tab slot="tab">Work</lea-tab>
  <lea-tab-panel slot="panel">
    Work page that showcases our work.
  </lea-tab-panel>
</lea-tabs>

There we go, Lea's component is already done, so let's write some documentation. See the live Lea tabs documentation page. You can see the full code of lea-tabs on github.

P.S.: Do note that Lea is now responsible for keeping the documentation of lea-tabs up to date herself, and improvements on Lion's documentation will not automatically be reflected on Lea's documentation.

Why Open Source?

Component libraries are in huge demand. By open-sourcing our extendable components, we help you to do your thing, while reaping all the benefits from the open-source community. What's more, is that any contribution made to Lion directly impacts and benefits every design system using it (including ing-web) on a global scale. This means we get the best of both worlds by helping people with our components, and getting valuable contributions from the community!

Take a look at our repository! and if you wanna stay up to date be sure to watch and/or star it - there is no twitter (yet) but you can follow me Thomas Allmer - hey there 👋

But there's more!

Building applications is hard, and sometimes, you need a little bit more than just the right component alone, but also things like: Validation, Forms, Overlays, Localization, etc. But fear not; Lion has got you covered!

You can check them out in our documentation, and we'll go into more depth about Lion's additional systems in future blog posts.

Thanks

Finally, we'd like to close this announcement by saying a few thank yous:

ING, for giving us the opportunity to work on this project, and make it great together with the open-source community.

Everyone who has worked on Lion (especially the Lion team), including all the contributors (36 contributors and counting!).

And last but not least Pascal Schilp, for turning my scribbles into a followable story.

Storybook for web components on steroids

Thomas Allmer — Thu, 28 Nov 2019 20:13:42 +0000

Building a web application is quite a big and challenging task.
As with many big tasks, it makes sense to break them into smaller pieces.
For applications, this usually means splitting your application into multiple separate components.

Once you start doing that you will notice that you have a lot of individual pieces in your hands, and that it can be tough to keep an overview of all these moving parts.

To solve this we have been recommending storybook since quite some time.

The support for web components has always been good (via @storybook/polymer), and it got even better with the recently added @storybook/web-components.

There are however some parts in storybook which are not fine-tuned for developing web components (the open-wc way).

Let's look at some of those points and how we can improve them.

You can follow along in the accompanying github repo

After a typical storybook setup it looks like this

$ start-storybook
info @storybook/web-components v5.3.0-alpha.40
info
info => Loading presets
info => Loading presets
info => Loading custom manager config.
info => Using default Webpack setup.
webpack built b6c5b0bf4e5f02d4df8c in 7853ms
╭───────────────────────────────────────────────────╮
│                                                   │
│   Storybook 5.3.0-alpha.40 started                │
│   8.99 s for manager and 8.53 s for preview       │
│                                                   │
│    Local:            http://localhost:52796/      │
│    On your network:  http://192.168.1.5:52796/    │
│                                                   │
╰───────────────────────────────────────────────────╯
# browser opens

When we compare this to starting a project with npm init @open-wc

$ npm run start
es-dev-server started on http://localhost:8000
  Serving files from '/my-demo'.
  Opening browser on '/my-demo/'
  Using history API fallback, redirecting non-file requests to '/my-demo/index.html'
# browser opens

The most obvious difference is that in one case we have 2 builds of ~8 seconds and in the other, we don't have any.

So why there are 2 builds?

To get an idea about why this might be needed we first need to understand some of the requirements of a universal demo system like storybook.

Excursion universal demo system

Let's assume we are a startup and we are creating a new app.
Our choice of technology is Vue.js. We happily start building our app and soon we see the need of having a demo system to show and work on all these individual components. Go forth they said and we built a demo system for vue.

It could look something like this

just some example code - don't read this as good vue code 😅

<template>
  <div class="hello">
    <h1>{{ msg }}</h1>
    <ul>
      <li v-for="demo in demos" v-on:click="showDemo(demo.name)">{{demo.name}}</li>
    </ul>

    <div v-html="demo"></div>
  </div>
</template>

<script>
  export default {
    name: 'HelloWorld',
    props: {
      msg: {
        type: String,
        default: 'My Demo System',
      },
      demos: {
        type: Array,
        default: () => [
          { name: 'Demo One', content: '<h1>Hey there from demo one</h1>' },
          { name: 'Demo Two', content: '<h1>I am demo two</h1>' },
        ],
      },
    },
    methods: {
      showDemo: function(name) {
        this.demoIndex = this.demos.findIndex(el => el.name === name);
      },
    },
    data() {
      return {
        demoIndex: -1,
      };
    },
    computed: {
      demo() {
        if (this.demoIndex >= 0) {
          return this.demos[this.demoIndex].content;
        }
        return '<h1>Please select a demo by clicking in the menu</h1>';
      },
    },
  };
</script>

The code here shows only the most relevant information
For a demo and more details look in the vue-demo-system folder
You can start it via npm i && npm run serve

Everything works, everyone is happy - life is good.

Fast forward 12 months and we got a new CIO. A new wind is blowing and with it a prosperous opportunity to work on a second app. The breeze, however, demands that this time it is written in Angular. No, problem - we are professionals and off we go working on the new app.
Pretty early we see a similar pattern as before - components everywhere and we need a way to work and demo them individually.
Ah we think that's easy we already have a system for that 😬

We give our best - but the angular components just don't wanna work well together with the vue demo app 😭.

What can we do? Do we really need to recreate the demo system for Angular now?

It seems our issue is that having the demo UI and the component demo on the same page has the unwanted side effect that we can only use the UI system within our demos.
Not very universal that is 😅
Could we split the UI and the demo?

How about using iframes and only communicate via postMessage?
Would that mean each window can do what they want? 🤞

Let's make a simple POC (proof of concept) with

a ul/li list as a menu
an iframe to show the demo

What we need:

We start with an empty menu
We listen to post messages of demos
The iframe gets loaded and the demos inside fires post messages
We then create menu items for each demo
On click on the menu item, we change the iframe url
If the iframe gets a demo to show it updates the html

Here is the index.html

<ul id="menu"></ul>
<iframe id="iframe" src="./iframe.html"></iframe>

<script>
  window.addEventListener('message', ev => {
    const li = document.createElement('li');
    li.addEventListener('click', ev => {
      iframe.src = `./iframe.html?slug=${slug}`;
    });
    menu.appendChild(li);
  });
</script>

Here is the iframe.html

<body>
  <h1>Please select a demo by clicking in the menu</h1>
</body>

<script>
  // Demo One
  if (window.location.href.indexOf('demo-one') !== -1) {
    document.body.innerHTML = '<h1>Hey there from demo two</h1>';
  }
  // Demo Two
  if (window.location.href.indexOf('demo-two') !== -1) {
    document.body.innerHTML = '<h1>I am demo two</h1>';
  }

  // register demos when not currently showing a demo
  if (window.location.href.indexOf('slug') === -1) {
    parent.postMessage({ name: 'Demo One', slug: 'demo-one' });
    parent.postMessage({ name: 'Demo Two', slug: 'demo-two' });
  }
</script>

The code here shows only the most relevant information
For a demo and more details look in the postMessage folder
You can start it via npm i && npm run start

Now imagine that the UI is way more than just a ul/li list and that the demo follows a certain demo format?
Could this be a system which allows the UI and the demo to be written in completely different technologies?

The answer is YES 💪

The only means of communication is done via postMessages.
Therefore the preview only needs to know which postMessage format to use.
Also, postMessage is a native function so every framework or system can use them.

Two builds (continued)

The above concept is what is used by storybook - which means that there are actually 2 applications being run.
One is the storybook UI (called manager) and one is your actual demo (called preview).
Knowing that it makes sense that there are 2 separate builds.

But why is there a build step at all? Why would storybook have such setup?

Let's see what is needed to allow for some code to be run and worked on in multiple browsers.

Excursion shipping code based on browser capabilities

Let's have a small example where we are using private class fields.
This feature is currently at stage 3 and only available in Chrome.

// index.js
import { MyClass } from './MyClass.js';

const inst = new MyClass();
inst.publicMethod();

// MyClass.js
export class MyClass {
  #privateField = 'My Class with a private field';

  publicMethod() {
    document.body.innerHTML = this.#privateField;
    debugger;
  }
}

We deliberately put a debugger breakpoint in there to see the actual code the browser is executing.

Let's see how webpack with a few babel plugins handles it. (see full config)

__webpack_require__.r(__webpack_exports__);
/* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "MyClass", function() { return MyClass; });
function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
function _defineProperties(target, props) {
// ... more helper functions

var MyClass =
/*#__PURE__*/
function () {
  function MyClass() {
    _classCallCheck(this, MyClass);

    _privateField.set(this, {
      writable: true,
      value: 'My Class with a private field'
    });
  }

  _createClass(MyClass, [{
    key: "publicMethod",
    value: function publicMethod() {
      document.body.innerHTML = _classPrivateFieldGet(this, _privateField);
      debugger;
    }
  }]);

  return MyClass;
}();

var _privateField = new WeakMap();

Wow that is quite some code 🙈 and it does not really look like the code written 😱

Note: in most cases you will not see this because of source maps

What happened? in a typical webpack & babel setup your code gets compiled down to es5 in order to be able to run the code also on older browser like IE11.

However, you may ask how often do I actually run my app in an older browser?

A typical developer should probably develop ~90% on a modern browser and ~10% on older browsers to make sure everything still works in order.
At least we hope you have such a nice workflow 🤗

So the question is why compile, ship, debug and work with this "strange" code 100% of the time if it's only needed for 10%?
Could we do better?

Let's see how es-dev-server handles it by opening the same file on chrome.

export class MyClass {
  #privateField = 'My Class with a private field';

  publicMethod() {
    document.body.innerHTML = this.#privateField;
    debugger;
  }
}

It looks exactly as the original code - because it is. The code as is was fully capable of running in chrome without any adjustments.
And that's what is happening it ships the source as is.

However, we are using private class fields which is an unsupported feature for example on Firefox.
What happens if we open it there?

it fails 😭

SyntaxError: private fields are not currently supported

ok, it's our fault as we are using a stage 3 feature and are not doing any compilation now.

Let's try it with es-dev-server --babel which in turn will use the same .babelrc as webpack.

The following code will be generated.

function _classPrivateFieldGet(receiver, privateMap) {
  var descriptor = privateMap.get(receiver);
  if (!descriptor) {
    throw new TypeError('attempted to get private field on non-instance');
  }
  if (descriptor.get) {
    return descriptor.get.call(receiver);
  }
  return descriptor.value;
}

export class MyClass {
  constructor() {
    _privateField.set(this, {
      writable: true,
      value: 'My Class with a private field',
    });
  }

  publicMethod() {
    document.body.innerHTML = _classPrivateFieldGet(this, _privateField);
    debugger;
  }
}

var _privateField = new WeakMap();

And it works 💪
It only compiles the private fields and not everything 👌

However, if you now go back to chrome you will see that it is now compiled there as well.
The reason for it is that once you start going through babel it just does it's thing based on @babel/preset-env and babel is always on the conservative side.

The real magic ✨ happens when you open it on an older browser like IE11.
As then it will compile it down to systemjs, a polyfill for es modules.

It will look something like this

System.register([], function(_export, _context)) {
  "use strict";

  var MyClass, _privateField;

  function _classCallback(instance, Constructor) {
// ...

It will behave exactly like real es modules, so that your code will work just fine on browsers which don't support them 💪

If you are concerned about speed it is best to only rely on stage 4 features and to not use babel at all.
You can if really needed use 2 start commands

"start": "es-dev-server --open",
"start:babel": "es-dev-server --babel --open",

So what es-dev-server auto mode enables is that you don't need to think about it.
It will be instant on modern browsers and will even work in these moments where you have a need to test in older browsers.

To summarize in order to be able to work with and debug code in all the browser we want to support we basically have 2 options.

Compile down to the lowest denominator
Serve code base on browser capabilities

And as always please don't go crazy with new features.
Use what is currently stable and available on your development browser.
You will have the best experience when you do not use a custom babel config.

The code here shows only the most relevant information
For a demo and more details look in the EsDevServer-vs-WebpackDevServer folder
You can start it via npm run start, npm run start:babel and npm run webpack

Source maps

Luckily in most cases, even when working with compiled code you will see the source code.
How is that possible? It's all thanks to Sourcemaps.
They are a way to map the original code to the compiled code and browser are smart enough to link them together and only show you what you are interested in.
As long as the option "Enable JavaScript source maps" is checked in your dev tools.

It is really awesome that it justs works. It is however yet another moving part that may break or you need to know about it at least.

Opportunity

So looking at compilation and shipping of modern code we see a window of opportunity.
We want to have the features of storybook but we also want to have the ease of use of not relying on webpack.

In short, the idea is to marry storybook ui with es-dev-server.

Let's get started 💪

Here is the master plan

Prebuild storybook ui (so we are not forced to use webpack)
Replace webpack magic like require.context
Mimic how the preview communicates with the manager
Use rollup to build a static version of storybook

Storybook on steroids

Prebuild storybook

In order to get an es module version of the storybook preview, it needs to go through webpack & rollup.
Yes, it is a little black magic but that was the only way that worked.
It seems storybook is not yet optimized to have a fully separated manager/preview.
But hey it works and we will collaborate with storybook to make this even better 💪

You can find the source on github and the output is published on npm as @open-wc/storybook-prebuilt.

Prebuilt has the following benefits:

fast
preview can be independent of storybooks build setup

Prebuilt has the following downsides:

you can not change the addons of a prebuilt
you can, however, create your own prebuilt

Replace webpack magic

In the current storybook require.context is used in preview.js to define which stories are loaded.
This is, however, a feature only available in webpack which basically means it is a lock in to a specific build tool.
We would like to free ourself to choose whatever we want so this needs to be replaced.

We opted for a command-line argument.

In short instead of defining where to look for stories in your js you now do it on the command line via

start-storybook --stories 'path/to/stories/*.stories.{js,mdx}'

Doing so allows exposing this value to various tools like koa-middlewares and rollup.

Mimic how the preview communicates with the manager

Now that we can "include/use" the storybook UI (manager) independent it's time to spin up es-dev-server.

For the manager, we create an index.html which boils down to a single import

<script src="path/to/node_modules/@open-wc/storybook-prebuilt/dist/manager.js"></script>

We do some special caching to make sure your browser only ever loads the storybook manager once.

For the preview, it is a little more as we need to load/register all the individual stories as shown in the postMessage example.
The list of stories we will get via the command line argument.

The important bits which end up being used by the browser is a dynamic import of all story files and then calling storybooks configure which will trigger a postMessage.

import { configure } from './node_modules/@open-wc/demoing-storybook/index.js';

Promise.all([
  import('/stories/demo-wc-card.stories.mdx'),
  // here an import to every story file will created
]).then(stories => {
  configure(() => stories, {});
});

Extra mdx support

The upcoming storybook 5.3.x (currently in beta) will introduce docs mode.
A special mode which allows writing markdown together with stories in a single file and it will be displayed on a single page.
You can think of it as Markdown but on steroids 😬

The format is called mdx and allows to write markdown but also to import javascript and write jsx.

We recommend it as the primary way to write documentation about your components.

In order to support such a feature es-dev-server needs to understand how to handle an mdx file.

For that, we added a koa middleware which converts requests to *.mdx files into the CSF (Component Story Format).

It basically means when you request http://localhost:8001/stories/demo-wc-card.stories.mdx and the file look like this on the file system:

###### Header

<Story name="Custom Header">
  {html`
    <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>
  `}
</Story>

it will server this to your browser

// ...
mdx('h6', null, `Header`);
// ...
export const customHeader = () => html`
  <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>
`;
customHeader.story = {};
customHeader.story.name = 'Custom Header';
customHeader.story.parameters = {
  mdxSource:
    'html`\n    <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>\n  `',
};

You can just open your Network Panel and look at the response 💪

Use rollup to build a static storybook

In most cases, you will also want to publish your storybook somewhere on a static server.
For that, we pre-setup a rollup configuration and which does all of the above and outputs 2 versions.

for modern browsers who support es modules and
for all other browsers we ship an es5 version with all polyfills

For more details on how the different versions are shipped from a static server please see the open-wc rollup recommendation.

The code here shows only the most relevant information
For a full demo see the storybookOnSteroids folder
You can start it via npm i && npm run storybook
For the actual source code see @open-wc/demoing-storybook

Verdict

We did it 💪

A fully-featured demo system that

is buildless on modern browsers
starts up lightning-fast
has a prebuilt UI
serves preview code based on browser capabilities
uses es-dev-server under the hood so you can use all its features

And above all, it's just wonderful to see how a completely separate server can power storybook.
The storybook setup is really worth it 👍

You can check it out in the open-wc repo
See a live example at https://open-wc.org/demoing-storybook/
And read the documentation documentation

PS: it's not all roses and rainbows but with that step, we now know that it is possible - further improvements like a smaller preview bundle or separate packages for the mdx transformation will happen at some point 🤗

Future

We hope that this can be a starting point so storybook can directly support other framework servers as well 👍
Even non JavaScript servers could be possible - Ruby, PHP are you ready? 🤗

If you are interested in supporting your frameworks server and you need help/guidance be sure to let us know.

Acknowledgements

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Benny and Lars for feedback and helping turn my scribbles to a followable story.

Cover Photo by Nong Vang on Unsplash

Generating TypeScript Definition Files from JavaScript

Thomas Allmer — Wed, 04 Sep 2019 09:44:52 +0000

At open-wc, we are big fans of buildless development setups. We have a post or two about it 😄. We believe that the future is all about coming back to the web platform. That means relying on native browser features in preference to userland or JavaScript solutions or development tools. That's why we have made it our mission to provide you the developer with the tools and techniques to use the platform today, even before legacy browsers are finally dropped.

This approach grants us tremendous advantages in DX, performance, and accessibility, but there are drawbacks. JavaScript, famously, is dynamically typed. Developers who want to enjoy type checking at development time will typically reach for Microsoft's TypeScript, Facebook's Flow, or Google's Clojure compiler. All of these require a build step.

Can we enjoy a safely typed developer experience while "staying true" to the web platform? Let's first dive in and see what Types can give us.

Examples in TypeScript

Let's say we want a function which takes a number or string and returns the square.

// helpers.test.ts
import { square } from '../helpers';

expect(square(2)).to.equal(4);
expect(square('two')).to.equal(4);

Our function's TypeScript implementation might look like this:

// helpers.ts
export function square(number: number) {
  return number * number;
}

I know what you're thinking: a string as an argument? While implementing, we discovered that that was a bad idea, too.

Thanks to the type safety of TypeScript, and the mature ecosystem of developer tools surrounding it like IDE support, we can tell before we even run our tests that square('two') will not work.

If we run the TypeScript compiler tsc on our files, we'll see the same error:

$ npm i -D typescript
$ npx tsc
helpers.tests.ts:8:19 - error TS2345: Argument of type '"two"' is not assignable to parameter of type 'number'.

8     expect(square('two')).to.equal(4);
                    ~~~~~

Found 1 error.

Type safety helped us catch this error before we pushed it to production. How can we accomplish this kind of type safety without using TypeScript as a build step?

Achieving Type Safety in Vanilla JavaScript

Our first step will be to rename our files from .ts to .js. Then we will use browser-friendly import statements in our JavaScript files by using relative urls with .js file extensions:

// helpers.test.js
import { square } from '../helpers.js';

expect(square(2)).to.equal(4);
expect(square('two')).to.equal(4);

Then, we will refactor our TypeScript function to JavaScript by stripping out the explicit type checks:

// helpers.js
export function square(number) {
  return number * number;
}

Now, if we go back to our test file, we no longer see the error at square('two'), when we pass the wrong type (string) to the function 😭!

If you're thinking "Oh well, JavaScript is dynamically typed, there's nothing to be done about it", then check this out: we actually can achieve type safety in vanilla JavaScript, using JSDoc comments.

Adding Types to JavaScript Using JSDoc

JSDoc is a long-standing inline documentation format for JavaScript. Typically, you might use it to automatically generate documentation for your server's API or your web component's attributes. Today, we're going to use it to achieve type safety in our editor.

First, add a JSDoc comment to your function. The docblockr plugin for VSCode and atom can help you do this quickly.

/**
 * The square of a number
 * @param {number} number
 * @return {number}
 */
export function square(number) {
  return number * number;
}

Next, we'll configure the TypeScript compiler to check JavaScript files as well as TypeScript files, by adding a tsconfig.json to our project's root directory.

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "lib": ["es2017", "dom"],
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": false,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "types": ["mocha"],
    "esModuleInterop": true
  },
  "include": ["test", "src"]
}

Hey! I thought you said we weren't going to be using TypeScript here?!

You're right, although we will be authoring and publishing browser-standard JavaScript, our editor tools will be using the TypeScript Language Server under the hood to provide us with type-checking.
Doing this allows us to get exactly the same behaviour in VSCode and Atom as with TypeScript.

We even get the same behaviour when running tsc.

$ npx tsc
test/helpers.tests.js:8:19 - error TS2345: Argument of type '"two"' is not assignable to parameter of type 'number'.

8     expect(square('two')).to.equal(4);
                    ~~~~~

Found 1 error.

Refactoring

Great, we've written our square feature, including type checks, and pushed it to production. But some time later, the product team came to us saying that an important customer wants to be able to increment the numbers we square for them before we apply the power. This time, the product team already spoke with QA, who worked through the night to provide the following tests for our refactored feature:

expect(square(2, 10)).to.equal(14);
expect(square(2, 'ten')).to.equal(14);

However, it appears that they probably should have spent those hours sleeping, as our original typecasting bug is still there.

How can we deliver this critical (😉) feature to our customers quickly while still maintaining type safety?

If we had implemented the feature in TypeScript, you might be surprised to learn that we don't need to add explicit type annotations to the second parameter, since we will supply it with a default value.

export function square(number: number, offset = 0) {
  return number * number + offset;
}

The provided default value let's TypeScript statically analyse the code to infer values type.

We can get the same effect using our vanilla-js-and-jsdoc production implementation:

/**
 * The square of a number
 * @param {number} number
 * @return {number}
 */
export function square(number, offset = 0) {
  return number * number + offset;
}

In both cases, tsc will give the error:

test/helpers.tests.js:13:22 - error TS2345: Argument of type '"ten"' is not assignable to parameter of type 'number'.

13     expect(square(2, 'ten')).to.equal(14);
                        ~~~~~

Also in both cases, the only thing we needed to add was offset = 0 as it contains the type information already. If we wanted to add an explicit type definition, we could have added a second @param {number} offset annotation, but for our purposes, this was unnecessary.

Publishing a Library

If you want people to be able to use your code, you're going to need to publish it at some point. For JavaScript and TypeScript, that typically means npm.
You will also want to provide your users with the same editor-level type safety that you've been enjoying.
To accomplish that, you can publish Type Declaration files (*.d.ts)in the root directory of the package you are publishing. TypeScript and the TypeScript Language Sever will respect those declaration files by default whenever they are found in a project's node_modules folder.

For TypeScript files, this is straightforward, we just add these options to tsconfig.json...

"noEmit": false,
"declaration": true,

...and TypeScript will generate *.js and *.d.ts files for us.

// helpers.d.ts
export declare function square(number: number, offset?: number): number;

// helpers.js
export function square(number, offset = 0) {
  return number * number + offset;
}

(Note that the output of the js file is exactly the same we wrote in our js version.)

Publishing JavaScript Libraries

Sadly, as of now tsc does not support generating *.d.ts files from JSDoc annotated files.
We hope it will in the future, and in fact, the original issue for the feature is still active, and it seems to be on board for 3.7. Don't take our word for it, the Pull Request is in flight.

In fact, this works so well that we are using it in production for open-wc.

!WARNING!
This is an unsupported version => if something does not work no one is going to fix it.
Therefore if your use-case is not supported you will need to wait for the official release of TypeScript to support it.

We took the liberty of publishing a forked version typescript-temporary-fork-for-jsdoc which is just a copy of the above pull request.

Generate TypeScript Definition Files for JSDoc Annotated JavaScript

So now that we have all the information. Let's make it work 💪!

Write your code in JS and apply JSDoc where needed
Use the forked TypeScript npm i -D typescript-temporary-fork-for-jsdoc
Have a tsconfig.json with at least the following:
```
"allowJs": true,
"checkJs": true,
```
Do "type linting" via tsc, ideally in a pre-commit hook via husky

Have tsconfig.build.json with at least

"noEmit": false,
"declaration": true,
"allowJs": true,
"checkJs": true,
"emitDeclarationOnly": true,

Generate Types via tsc -p tsconfig.build.types.json, ideally in CI
Publish both your .js and .d.ts files

We have exactly this setup at open-wc and it served us well so far.

Congratulations you now have type safety without a build step 🎉

Feel free to also check out the repository for this post and execute npm run build:types or npm run lint:types to see the magic live.

Conclusions

To sum it all up - why are we fans of TypeScript even though it requires a build step?

It comes down to 2 things:

Typings can be immensely useful (type safety, auto-complete, documentation, etc.) for you and/or your users
TypeScript is very flexible and supports types for "just" JavaScript as well

Further Resources

If you'd like to know more about using JSDoc for type safety, we recommend the following blog posts:

Acknowledgements

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Benny, Lars and Pascal for feedback and helping turn my scribbles to a followable story.

Nested Dependencies in Frontend

Thomas Allmer — Tue, 02 Jul 2019 16:08:49 +0000

So you got this awesome idea and now you want to actually do it. I'm pretty sure you do not want to start from scratch, so let's use existing open source packages.

If you want to play along, all the code is on github.

For our example case, we wanna use lit-element and lit-html.

mkdir nested-dependecies-in-frontend
cd nested-dependecies-in-frontend
npm install lit-element lit-html@1.0.0 --save-exact

Note: we are using pinned versions on purpose here.

Then we just load both packages in our main.js.

import { LitElement } from "lit-element";
import { html } from "lit-html";

console.log(LitElement);
console.log(html);

In order to find out how big our app will be, we would like to create a rollup bundle. First, install Rollup:

npm install -D rollup

Then create a rollup.config.js

export default {
  input: "main.js",
  output: {
    file: "bundle.js",
    format: "iife"
  },
};

Next, add "build": "rollup -c rollup.config.js && du -h bundle.js" to our package.json's scripts block, so we can easily build the file and output it's file size.
Lets run it via npm run build :)

(!) Unresolved dependencies
https://rollupjs.org/guide/en#warning-treating-module-as-external-dependency
lit-element (imported by main.js)
lit-html (imported by main.js)

Oh! It doesn't work! 😭

OK, I've heard this one before... We need to add some plugins so that Rollup will understand the way node resolution (i.e. bare module specifiers like import { html } from 'lit-html') works.

npm i -D rollup-plugin-node-resolve

+ import resolve from "rollup-plugin-node-resolve";
+
   export default {
    input: "main.js",
    output: {
      file: "bundle.js",
      format: "iife"
    },
+  plugins: [resolve()]
  };

$ npm run build
# ...
created bundle.js in 414ms
96K     bundle.js

So that seems to work fine. 💪

What Happens if Someone Prefers yarn?

Doing a yarn install and then a build should result in the same output, right?

$ yarn install
$ yarn build
# ...
created bundle.js in 583ms
124K    bundle.js

Wow! That is unexpected - 124K for the yarn build vs. 96K for npm?
It seems the yarn build contains some extra files... maybe a package was duplicated?

$ yarn list --pattern lit-*
├─ lit-element@2.2.0
│  └─ lit-html@1.1.0
└─ lit-html@1.0.0

Yup, both lit-html versions 1.0.0 and 1.1.0 are installed.
The reason is most likely that we pinned lit-html to version 1.0.0 in our root dependency when we installed it with the npm install --save-exact lit-html@1.0.0 command, above.

While npm seems to dedupe it fine, I don't feel safe using npm because if the dependency tree becomes bigger npm also likes to install nested dependencies.

$ npm ls lit-element lit-html
├─┬ lit-element@2.2.0
│ └── lit-html@1.0.0  deduped
└── lit-html@1.0.0

Also specially when you use some beta (e.g. 0.x.x) dependencies it becomes very tricky. As in this case SemVer says every 0.x.0 release means a breaking change. This means 0.8.0 is treated as incompatible with 0.9.0. Therefore even if the APIs you are using would work just fine with both versions you will always get nested dependencies which may break your application silently. e.g. there will be no warning or information on the terminal 😱

How Node Resolution Works

In nodejs, when you import a file using a bare specifier, e.g. import { LitElement } from "lit-element"; Node's module resolver function gets the string lit-element, and begins searching all of the directories listed in module.paths for the importing module, which you can inspect like any other value in the node REPL:

$ node
module.paths
[
  '/some/path/nested-dependencies-in-frontend/node_modules',
  '/some/path/node_modules',
  '/some/node_modules',
  '/node_modules',
]
# unimportant folders are hidden here

Basically, node looks into every node_modules folder, starting in the module's parent directory and moving up the file tree, until it finds a directory name which matches the module specifier (in our case, lit-element). The resolution algorithm always starts at the current module's parent directory, so it's always relative to where you are importing the file from. If we would inspect module.paths from within lit-element's directory, we'd see a different list.

$ cd node_modules/lit-element
$ node
module.paths
[
  '/some/path/nested-dependencies-in-frontend/node_modules/lit-element/node_modules',
  '/some/path/nested-dependencies-in-frontend/node_modules',
  '/some/path/node_modules',
  '/some/node_modules',
  '/node_modules',
]

Now we can understand what node's nested dependencies are. Every module can have it's own node_modules directory, ad nauseum, and imports referenced in that module's files will always look in their closest node_modules directory first...

Pros of Nested Dependencies on Node	Cons of Nested Dependencies for Frontend
Every package can have their own versions of every dependency	Shipping the same code twice means longer download and processing times
Packages are not influenced by dependencies of other packages in the application	Stuff might break if the same code is imported twice from two different locations (e.g. performance optimizations via WeakMaps or singletons)
There is no "high fee" to pay for accessing many extra files.	Checking if a file exists is an extra request
On the server, you usually do not care too much about how much extra code (in files size) there is	Overall, in short, your site will get slower

The Problems

In short, automatic module resolution that prefers nesting may be dangerous for frontend.

We care about loading and parsing performance
We care about file size
Some packages must be singletons (i.e. unique in the module graph) to work properly in our application
- Examples include lit-html and graphql
We should be in full control of what ends up on the client's browser

Node-style module resolution, which was designed for a server-side environment, can turn these concerns into serious issues when adopted in the browser.
IMHO, even if node resolution makes it technically possible, loading the code for a complex data-grid more than once should never be our goal as frontend developers.

Solutions

Thankfully, there are solutions to these problems that we can use today, and proposals on the horizon which will altogether eliminate the need for such workarounds in the future.

Making it Work Today

Here are some tips to work with bare module specifiers in your front end code today:

Make sure that the modules in your dependency tree all use similar version ranges of their common dependencies
Avoid pinning specific package versions (like we did above with npm i -S lit-html@1.0.0) wherever possible
If you're using npm:
- Run npm dedupe after installing packages to remove nested duplicates.
- You can try deleting your package-lock.json and do a fresh install. Sometimes it magically helps 🧙‍♂️
If you're using yarn:
- Consider using yarn resolutions to specify your preferred version of any duplicated packages

A Look Into the Future

If we could tell the JavaScript environment (i.e. the browser) exactly at which path to find the file specified by some string, we would have no need for node-style resolution or programming-time deduplication routines.
We'd write something like this and pass it to the browser to specify which paths mapped to which packages:

{
  "lit-html": "./node_modules/lit-html.js",
  "lit-element": "./node_modules/lit-element.js"
}

Using this import map to resolve package paths means there would always only be one version of lit-html and lit-element, because the global environment already knows exactly where to find them.

Luckily ✨, this is already a proposed spec called import maps. And since it's meant for the browser there's no need to do any transformation at all! You just provide the map and you don't need any build step while developing?

Sounds crazy 😜? Let's try it out! 🤗

Note: Mind you this is an experimental API proposal, it hasn't been finalized or accepted by implementers.

It currently only works in Chrome 75+, behind a flag.
So enter chrome://flags/ in the URL bar and then search for Built-in module infra and import maps and enable it.
Here is a direct link to it: chrome://flags/#enable-built-in-module-infra.

Using Import Maps in the Browser

In order to use an import map, let's create an index.html file.

<html lang="en-GB">
<head>
  <script type="importmap">
    {
      "imports": {
        "lit-html": "./node_modules/lit-html/lit-html.js",
        "lit-html/": "./node_modules/lit-html/",
        "lit-element": "./node_modules/lit-element/lit-element.js",
        "lit-element/": "./node_modules/lit-element/"
      }
    }
  </script>
  <title>My app</title>
</head>

<body>
  <crowd-chant>
    <span slot="what">Bare Imports!</span>
    <span slot="when">Now!</span>
  </crowd-chant>

  <script type="module" src="./main.js"></script>
</body>

</html>

and adjust the main.js.

import { html, LitElement } from "lit-element";

class CrowdChant extends LitElement {
  render() {
    return html`
      <h2>What do we want?</h2>
      <slot name="what"></slot>
      <h2>When do we want them?</h2>
      <time><slot name="when">Now!</slot></time>
    `;
  }
}

customElements.define("crowd-chant", CrowdChant);

Save the file then serve it locally by running npx http-server -o in the same directory.
This will open http://localhost:8080/ where you will see your custom element rendered on screen. 🎉

What kind of black magic is this 🔮? Without any bundlers, tools, or build step, we wrote a componentized app with the kind of bare specifiers we've come to know and love.

Lets break it down:

import { html } from 'lit-html';
// will actually import "./node_modules/lit-html/lit-html.js"
// because of
// "lit-html": "./node_modules/lit-html/lit-html.js",

import { repeat } from 'lit-html/directives/repeat.js'
// will actually import "./node_modules/lit-html/directives/repeat.js"
// beacause of
// "lit-html/": "./node_modules/lit-html/",

So this means

You can import packages directly since the package name is mapped to a specific file
You can import subdirectories and files, since packageName + '/' is mapped to its directory
You must not omit the .js when importing a file from a subdirectory

What Does this All Mean for my Production Build?

It's important to once again note that this is still experimental technology. In any event, you may still want to do an optimized build for production sites using tools like Rollup. We are exploring together what these new APIs will do for our websites and apps. The underlying import-maps proposal is still unstable, but that shouldn't stop us from experimenting and extracting utility from it. After all, most of us are comfortable using babel to enable experimental syntax like decorators, even though that proposal has at time of this writing at least four flavours.

If you want to try import maps today even in unsupported browsers, you'll need either a build step or a runtime solution like systemjs. For the build-step option, you'll replace the rollup-plugin-node-resolve with something that respects your import map instead of using node resolution.

And wouldn't it be really nice if you could just point rollup to your index.html and have it figure out what your entry points are and if there is an import map?

That's why at open-wc we're releasing experimental support for import maps with our rollup-plugin-index-html.

And you can read all about it here on dev.to. Watch this space for the announcement 😉.

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Benny and Lars for feedback and helping turn my scribbles to a followable story.

Testing Workflow for Web Components

Thomas Allmer — Tue, 09 Apr 2019 17:55:38 +0000

Whenever you ship something to be used by others, you take on a responsibility to deliver safe and stable code. One way to address this is by testing your code.

No matter how small - no matter how simple your project, there should always ideally be tests.

Yes, I know reality hits hard and there will be many cases where that doesn't happen - but you should always strive to have tests

Disclaimer

In this tutorial, we're going to make a simple version of an input element. By the end of it, you'll gain the skills and knowledge to put open-wc testing tools to practice; and build a solid, accessible, and well-tested input component.

Warning

This is an in-depth tutorial showing a few pitfalls and tough cases when working with web components. This is definitely for more advanced users. You should have a basic knowledge about LitElement and JSDoc Types. Having an idea what Mocha, Chai BDD, Karma is might help a little as well.

We are thinking about posting an easier digestible version of this so if that is something you would like to see - let us know in the comments.

If you want to play along - all the code is on github.

Let's Get Started!

Run in your console

$ npm init @open-wc

# Results in this flow
✔ What would you like to do today? › Scaffold a new project
✔ What would you like to scaffold? › Web Component
# Select with space! "Testing" => just enter will move one with no selection
✔ What would you like to add? › Testing
✔ Would you like to scaffold examples files for? › Testing
✔ What is the tag name of your application/web component? … a11y-input
✔ Do you want to write this file structure to disk? › Yes
Writing..... done
✔ Do you want to install dependencies? › No

For more details please see https://open-wc.org/testing/.

Delete src/A11yInput.js

Modify src/a11y-input.js to:

import { LitElement, html, css } from 'lit-element';

export class A11yInput extends LitElement {}

customElements.define('a11y-input', A11yInput);

and test/a11y-input.test.js to:

/* eslint-disable no-unused-expressions */
import { html, fixture, expect } from '@open-wc/testing';

import '../src/a11y-input.js';

/**
 * @typedef {import('../src/a11y-input.js').A11yInput} A11yInput
 */

describe('a11y input', () => {
  it('has by default an empty string as label', async () => {
    const el = /** @type {A11yInput} */ (await fixture('<a11y-input></a11y-input>'));
    expect(el.label).to.equal('');
  });
});

Our tests so far consist of a single feature (the label property) and a single assertion (expect). We're using karma and chai's BDD syntax, so we group sets of tests (it) under the features or APIs they relate to (describe).

Let's see if everything works correctly by running: npm run test.

SUMMARY:
✔ 0 tests completed
✖ 1 test failed

FAILED TESTS:
  a11y input
    ✖ has by default an empty string as label
      HeadlessChrome 73.0.3683 (Windows 10.0.0)
    AssertionError: expected undefined to equal ''

      + expected - actual

      -[undefined]
      +""

Awesome - just as expected (🥁), we have a failing test :)

Let's switch into watch mode, which will run the tests continuously whenever you make changes to your code.

npm run test:watch

The following code was added in the video above to src/a11y-input.js:

static get properties() {
  return {
    label: { type: String },
  };
}

constructor() {
  super();
  this.label = '';
}

So far, so good? Still with us? Great! Let's up the game a little...

Adding a Test for Shadow DOM

Let's add an assertion to test the contents of our element's shadow root.

If we want to be sure that our element behaves/looks the same we should make sure its dom structure remains the same.
So let's compare the actual shadow dom to what we want it to be.

it('has a static shadowDom', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input></a11y-input>
  `));
  expect(el.shadowRoot.innerHTML).to.equal(`
    <slot name="label"></slot>
    <slot name="input"></slot>
  `);
});

As expected, we get:

✖ has a static shadowDom
AssertionError: expected '' to equal '\n      <slot name="label"></slot>\n      <slot name="input"></slot>\n    '

  + expected - actual

  +
  +      <slot name="label"></slot>
  +      <slot name="input"></slot>
  +

So let's implement that in our element.

render() {
  return html`
    <slot name="label"></slot>
    <slot name="input"></slot>
  `;
}

Interesting, the test should be green... but it's not 🤔 Let's take a look.

✖ has a static shadowDom
AssertionError: expected '<!---->\n      <slot name="label"></slot>\n      <slot name="input"></slot>\n    <!---->' to equal '\n        <slot name="label"></slot>\n        <slot name="input"></slot>\n    '

  + expected - actual

  -<!---->
  -      <slot name="label"></slot>
  -      <slot name="input"></slot>
  -    <!---->
  +
  +        <slot name="label"></slot>
  +        <slot name="input"></slot>
  +

You may have noticed those weird empty comment  tags. They are markers that lit-html uses to remember where dynamic parts are, so it can be updated efficiently. For testing, however, this can be a little annoying to deal with.

If we use innerHTML to compare the DOM, we'd have to rely on simple string equality. Under those circumstances, we'd have to exactly match the generated DOM's whitespace, comments, etc; in other words: it will need to be a perfect match. Really all we need to test is that the elements we want to render are rendered. We want to test the semantic contents of the shadow root.

Fortunately, we've got you covered. If you're using @open-wc/testing then it automatically loads the @open-wc/semantic-dom-diff chai plugin for us to use.

So let's try it out 💪

// old:
expect(el.shadowRoot.innerHTML).to.equal(`...`);

// new:
expect(el).shadowDom.to.equal(`
  <slot name="label"></slot>
  <slot name="input"></slot>
`);

Bam 🎉

a11y input
  ✔ has by default an empty string as a label
  ✔ has a static shadowDom

How does shadowDom.to.equal() work?

It gets the innerHTML of the shadow root
Parses it (actually, the browser parses it - no library needed)
Normalizes it (potentially every tag/property on its own line)
Parses and normalizes the expected HTML string
Passes both normalized DOM strings on to chai's default compare function
In case of failure, groups, and displays any differences in a clear manner

If you want to know more, please check out the documentation of semantic-dom-diff.

Testing the "Light" DOM

We can do exactly the same thing with the light DOM. (The DOM which will be provided by our user or our defaults, i.e. the element's children).

it('has 1 input and 1 label in light-dom', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input .label=${'foo'}></a11y-input>
  `));
  expect(el).lightDom.to.equal(`
    <label slot="label">foo</label>
    <input slot="input">
  `);
});

And let's implement it.

connectedCallback() {
  super.connectedCallback();
  this.labelEl = document.createElement('label');
  this.labelEl.innerText = this.label;
  this.labelEl.setAttribute('slot', 'label');
  this.appendChild(this.labelEl);

  this.inputEl = document.createElement('input');
  this.inputEl.setAttribute('slot', 'input');
  this.appendChild(this.inputEl);
}

So we tested our light and shadow dom 💪 and our tests run clean 🎉

Note: Using the DOM API in a lit-element's lifecycle is an anti-pattern, however to allow for a11y it might be a real use case - anyways it's great for illustration purposes

Using Our Element in an App

So now that we have a basic a11y input let's use it - and test it - in our application.

Again we start with a skeleton src/my-app.js

/* eslint-disable class-methods-use-this */
import { LitElement, html, css } from 'lit-element';

export class MyApp extends LitElement {}

customElements.define('my-app', MyApp);

And our test in test/my-app.test.js;

/* eslint-disable no-unused-expressions */
import { html, fixture, expect } from '@open-wc/testing';

import '../src/my-app.js';

/**
 * @typedef {import('../src/my-app.js').MyApp} MyApp
 */

describe('My Filter App', () => {
  it('has a heading and a search field', async () => {
    const el = /** @type {MyApp} */ (await fixture(html`
      <my-app .label=${'foo'}></my-app>
    `));
    expect(el).shadowDom.to.equal(`
      <h1>My Filter App</h1>
      <a11y-input></a11y-input>
    `);
  });
});

Run the test => fails and then we add the implementation to src/a11y-input.js

render() {
  return html`
    <h1>My Filter App</h1>
    <a11y-input></a11y-input>
  `;
}

But oh no! That should be green now...

SUMMARY:
✔ 3 tests completed
✖ 1 test failed

FAILED TESTS:
  My Filter App
    ✖ has a heading and a search field
    AssertionError: expected '<h1>\n  My Filter App\n</h1>\n<a11y-input>\n  <label slot="label">\n  </label>\n  <input slot="input">\n</a11y-input>\n' to equal '<h1>\n  My Filter App\n</h1>\n<a11y-input>\n</a11y-input>\n'

      + expected - actual

       <h1>
         My Filter App
       </h1>
       <a11y-input>
      -  <label slot="label">
      -  </label>
      -  <input slot="input">
       </a11y-input>

What is happening?
Do you remember that we had a specific test to ensure the light-dom of a11y-input?
So even if the users only puts <a11y-input></a11y-input> in his code - what actually comes out is

<a11y-input>
  <label slot="label"></label>
  <input slot="input">
</a11y-input>

e.g. a11y-input is actually creating nodes inside of your my-app shadow dom. Preposterous! For our example here we say that's what we want.
So how can we still test it?

Luckily .shadowDom has another ace up its sleeve; it allows us to ignore parts of dom.

expect(el).shadowDom.to.equal(`
  <h1>My Filter App</h1>
  <a11y-input></a11y-input>
`, { ignoreChildren: ['a11y-input'] });

We can even specify the following properties as well:

ignoreChildren
ignoreTags
ignoreAttributes (globally or for specific tags)

For more details please see semantic-dom-diff.

Snapshot testing

If you have a lot of big dom trees writing/maintaining all those manually written expects is going to be tough.
To help you with that there are semi/automatic snapshots.

So if we change our code

// from
expect(el).shadowDom.to.equal(`
  <slot name="label"></slot>
  <slot name="input"></slot>
`);

// to
expect(el).shadowDom.to.equalSnapshot();

If we now execute npm run test it will create a file __snapshots__/a11y input.md and fill it with something like this

# `a11y input`

#### `has a static shadowDom`

``html
<slot name="label">
</slot>
<slot name="input">
</slot>

``

What we wrote before by hand can now be auto-generated on init or forcefully via npm run test:update-snapshots.

If the file __snapshots__/a11y input.md already exists it will compare it with the output and you will get errors if your html output changed.

FAILED TESTS:
  a11y input
    ✖ has a static shadowDom
      HeadlessChrome 73.0.3683 (Windows 10.0.0)
    AssertionError: Received value does not match stored snapshot 0

      + expected - actual

      -<slot name="label-wrong">
      +<slot name="label">
       </slot>
       <slot name="input">
      -</slot>
      +</slot>

For more details please see semantic-dom-diff.

I think that's now enough about comparing dom trees...
It's time for a change 🤗

Code coverage

Another useful metric we get when testing with the open-wc setup is code coverage.
So what does it mean and how can we get it? Code coverage is a measure of how much of our code is checked by tests. If there's a line, statement, function, or branch (e.g. if/else statement) that our tests don't cover our coverage score will be affected.
A simple npm run test is all we need and you will get the following:

=============================== Coverage summary ===============================
Statements   : 100% ( 15/15 )
Branches     : 100% ( 0/0 )
Functions    : 100% ( 5/5 )
Lines        : 100% ( 15/15 )
================================================================================

Which means that 100% of our code's statements, branches, functions, and lines are covered by tests. Pretty neat!

So let's go the other way and add code to src/a11y-input.js before adding a test. Let's say we want to access the value of our input directly via our custom element and whenever its value is 'cat' we want to log something.

get value() {
  return this.inputEl.value;
}

set value(newValue) {
  if (newValue === 'cat') {
    console.log('We like cats too :)');
  }
  this.inputEl.value = newValue;
}

It's a vastly different result

SUMMARY:
✔ 4 tests completed
TOTAL: 4 SUCCESS

=============================== Coverage summary ===============================
Statements   : 81.82% ( 18/22 )
Branches     : 0% ( 0/2 )
Functions    : 75% ( 6/8 )
Lines        : 81.82% ( 18/22 )
================================================================================
06 04 2019 10:40:45.380:ERROR [reporter.coverage-istanbul]: Coverage for statements (81.82%) does not meet global threshold (90%)
06 04 2019 10:40:45.381:ERROR [reporter.coverage-istanbul]: Coverage for lines (81.82%) does not meet global threshold (90%)
06 04 2019 10:40:45.381:ERROR [reporter.coverage-istanbul]: Coverage for branches (0%) does not meet global threshold (90%)
06 04 2019 10:40:45.381:ERROR [reporter.coverage-istanbul]: Coverage for functions (75%) does not meet global threshold (90%)

Our coverage is way lower than before. Our test command even fails, even though all the tests run successfully.
This is because by default open-wc's config sets a 90% threshold for code coverage.

If we want to improve coverage we need to add tests - so let's do it

it('can set/get the input value directly via the custom element', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input .value=${'foo'}></a11y-input>
  `));
  expect(el.value).to.equal('foo');
});

uh oh 😱 we wanted to improve coverage but now we need fix an actual bug first 😞

FAILED TESTS:
  a11y input
    ✖ can set/get the input value directly via the custom element
    TypeError: Cannot set property 'value' of null        at HTMLElement.set value [as value]
    // ... => long error stack

That was unexpected... on first glance, I don't really know what that means... better to check some actual nodes and inspect them in the browser.

Debugging in the Browser

When we run our test with watch, karma sets up a persistent browser environment to run tests in.

Be sure you started with npm run test:watch
visit http://localhost:9876/debug.html

You should see something like this

You can click on the circled play button to only run one individual test.

So let's open the Chrome Dev Tools (F12) and put a debugger in the test code.

it('can set/get the input value directly via the custom element', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input .value=${'foo'}></a11y-input>
  `));
  debugger;
  expect(el.value).to.equal('foo');
});

Dang.. the error happens even before that point...
"Fatal" errors like this are a little tougher as they are not failing tests but sort of a complete meltdown of your full component.

Ok, let's put some code in the setter directly.

set value(newValue) {
  debugger;

Alright, that worked so our chrome console we write console.log(this) let's see what we have here

<a11y-input>
  #shadow-root (open)
</a11y-input>

Ahh there we have it - the shadow dom is not yet rendered when the setter is called.
So let's be safe and add a check before

set value(newValue) {
  if (newValue === 'cat') {
    console.log('We like cats too :)');
  }
  if (this.inputEl) {
    this.inputEl.value = newValue;
  }
}

Fatel error is gone 🎉
But we now have a failing test 😭

✖ can set/get the input value directly via the custom element
AssertionError: expected '' to equal 'foo'

We may need a change of tactic 🤔
We can add it as a separate value property and sync when needed.

static get properties() {
  return {
    label: { type: String },
    value: { type: String },
  };
}

constructor() {
  super();
  this.label = '';
  this.value = '';
  // ...
}

update(changedProperties) {
  super.update(changedProperties);
  if (changedProperties.has('value')) {
    if (this.value === 'cat') {
      console.log('We like cats too :)');
    }
    this.inputEl.value = this.value;
  }
}

And we're finally back in business! 🎉

ok bug fixed - can we please get back to coverage? thank you 🙏

Back to coverage

With this added test we made some progress.

=============================== Coverage summary ===============================
Statements   : 95.83% ( 23/24 )
Branches     : 50% ( 2/4 )
Functions    : 100% ( 7/7 )
Lines        : 95.83% ( 23/24 )
================================================================================
06 04 2019 13:18:54.902:ERROR [reporter.coverage-istanbul]: Coverage for branches (50%) does not meet global threshold (90%)

However we are still not fully there - the question is why?

To find out open coverage/index.html in your browser. No web server needed just open the file in your browser - on a mac you can do that from the command line with open coverage/index.html

You will see something like this

Once you click on a11y-input.js you get a line by line info how often they got executed.
So we can immediately see which lines are not executed yet by our tests.

So let's add a test for that

it('logs "We like cats too :)" if the value is "cat"', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input .value=${'cat'}></a11y-input>
  `));
  // somehow check that console.log was called
});

=============================== Coverage summary ===============================
Statements   : 100% ( 24/24 )
Branches     : 75% ( 3/4 )
Functions    : 100% ( 7/7 )
Lines        : 100% ( 24/24 )
================================================================================

With that, we are back at 100% on statements but we still have something missing on branches.
Let's see why?

This E means else path not taken.
So whenever the function update gets called there is always a property value in the changedProperties.

We have label as well so it's a good idea to test it. 👍

it('can update its label', async () => {
  const el = /** @type {A11yInput} */ (await fixture('<a11y-input label="foo"></a11y-input>'));
  expect(el.label).to.equal('foo');
  el.label = 'bar';
  expect(el.label).to.equal('bar');
});

boom 100% 💪 we win 🥇

=============================== Coverage summary ===============================
Statements   : 100% ( 24/24 )
Branches     : 100% ( 4/4 )
Functions    : 100% ( 7/7 )
Lines        : 100% ( 24/24 )
================================================================================

But wait we didn't even finish the test above - the code is still

  // somehow check that console.log was called

How come we have 100% test coverage?

Lets first try to understand how code coverage works 🤔
The way code coverage gets measured is by applying a form of instrumentation. In short, before our code is executed it gets changed (instrumented) and it behaves something like this:

Note: This is a super simplified version for illustration purposes.

if (this.value === 'cat') {
  console.log('We like cats too :)');
}

// becomes something like this (psoido code)
__instrumented['functionUpdate'] += 1;
if (this.value === 'cat') {
  __instrumented['functionUpdateBranch1yes'] += 1;
  console.log('We like cats too :)');
} else {
  __instrumented['functionUpdateBranch1no'] += 1;
}

Basically, your code gets littered with many many flags. Based on which flags get trigger a statistic gets created.

So 100% test coverage only means that every line you have in your code was executed at least once after all your tests finished. It does not mean that you tested everything, or if your tests make the correct assertions.

So even though we already have 100% code coverage we are still going to improve our log test.

You should, therefore, see code coverage as a tool that only gives you guidance and help on spotting some missing tests, rather than a hard guarantee of code quality.

Spying on Code

If you want to check how often or with which parameters a function gets called, that's called spying.
open-wc recommends the venerable sinon package, which provides many tools for spying and other related tasks.

npm i -D sinon

So you create a spy on a specific object and then you can check how often it gets called.

import sinon from 'sinon';

it('outputs "We like cats too :)" if the value is set to "cat"', async () => {
  const logSpy = sinon.spy(console, 'log');
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input></a11y-input>
  `));

  el.value = 'cat';
  expect(logSpy.callCount).to.equal(1);
});

Uh oh... the test fails:

AssertionError: expected 0 to equal 1

Messing with global objects like console might have side effects so let's better refactor using a dedicated log function.

update(changedProperties) {
  super.update(changedProperties);
  if (changedProperties.has('value')) {
    if (this.value === 'cat') {
      this.log('We like cats too :)');
    }
    this.inputEl.value = this.value;
  }
}

log(msg) {
  console.log(msg);
}

This result in no global object in our test code - sweet 🤗

it('logs "We like cats too :)" if the value is set to "cat"', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input></a11y-input>
  `));
  const logSpy = sinon.spy(el, 'log');

  el.value = 'cat';
  expect(logSpy.callCount).to.equal(1);
});

However, we still get the same error. Let's debug... boohoo apparently update is not sync - a wrong assumption I made 🙈 I am saying assumptions are dangerous quite often - still I fall for it from time to time 😢.

So what can we do? Sadly there seems to be no public api to do some sync actions triggered by an property update.
Let's create an issue for it https://github.com/Polymer/lit-element/issues/643.

For now apparently, the only way is to rely on a private api. 🙈
Also, we needed to move the value sync to updated so it gets executed after every dom render.

_requestUpdate(name, oldValue) {
  super._requestUpdate(name, oldValue);
  if (name === 'value') {
    if (this.value === 'cat') {
      this.log('We like cats too :)');
    }
  }
}

updated(changedProperties) {
  super.updated(changedProperties);
  if (changedProperties.has('value')) {
    this.inputEl.value = this.value;
  }
}

and here is the updated test for the logging

it('logs "We like cats too :)" if the value is set to "cat"', async () => {
  const el = /** @type {A11yInput} */ (await fixture(html`
    <a11y-input></a11y-input>
  `));
  const logSpy = sinon.spy(el, 'log');

  el.value = 'cat';
  expect(logSpy.callCount).to.equal(1);
  expect(logSpy.calledWith('We like cats too :)')).to.be.true;

  // different values do NOT log
  el.value = 'foo';
  expect(logSpy.callCount).to.equal(1);

  el.value = 'cat';
  expect(logSpy.callCount).to.equal(2);
});

wow, that was a little tougher than expected but we did it 💪

SUMMARY:
✔ 7 tests completed
TOTAL: 7 SUCCESS

Running Tests Without Karma Framework

The Karma framework is powerful and feature-rich, but sometimes we might want to pare-down our testing regiment. The nice thing with everything we proposed so far is that we only used browser-standard es modules with no need for transpilation, with the one exception of bare modules specifiers.
So just by creating a test/index.html.

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <link href="../node_modules/mocha/mocha.css" rel="stylesheet" />
  <script src="../node_modules/mocha/mocha.js"></script>
  <script src="../node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js"></script>
</head>
<body>
  <div id="mocha"></div>
  <script>
    mocha.setup('bdd');
  </script>

  <script type="module">
    import './a11y-input.test.js';
    import './my-app.test.js';

    mocha.checkLeaks();
    mocha.run();
  </script>
</body>
</html>

and opening it via owc-dev-server in chrome, it will work perfectly fine.
We got everything up and running without webpack or karma - sweet 🤗

Do the Cross-Browser Thing

We now feel pretty comfortable with our web component. It's tested and covered; there's just one more step - we want to make sure it runs and is tested in all browsers.

Open WC recommends Browserstack for cross-browser testing. If you haven't set it up yet, you can do it now - here is the link again - https://open-wc.org/testing/.

So let's just run it

npm run test:bs

SUMMARY:
✔ 42 tests completed
TOTAL: 42 SUCCESS

Yeah, that works nicely! 🤗

If there are failing tests it will output them in the summary with the specific browser where it failed.

SUMMARY:
✔ 40 tests completed
✖ 2 tests failed

FAILED TESTS:
  a11y input
    ✖ has a static shadowDom
      Firefox 64.0.0 (Windows 10.0.0)
      Safari 12.0.0 (Mac OS X 10.14.0)
    expected '<slot name="label">\n</slot>\n<slot name="input">\n</slot>\n<style>\n</style>\n' to equal '<slot name="label">\n</slot>\n<slot name="input">\n</slot>\n'

      + expected - actual

       <slot name="label">
       </slot>
       <slot name="input">
       </slot>
      -<style>
      -</style>

If you need to debug a particular browser:

npm run test:legacy:watch
visit http://localhost:9876/debug.html with that browser (either it locally or via browserstack)
select a specific test (or use it.only() in code)
start debugging

Also if you want to adjust the browser that gets tested you can adjust your karma.bs.config.js.

For example, if you want to add the Firefox ESR to your list.

module.exports = config => {
  config.set(
    merge(bsSettings(config), createBaseConfig(config), {
      browserStack: {
        project: 'testing-workflow-for-web-components',
      },
      browsers: [
        'bs_win10_firefox_ESR',
      ],
      // define browsers
      // https://www.browserstack.com/automate/capabilities
      customLaunchers: {
        bs_win10_firefox_ESR: {
          base: 'BrowserStack',
          browser: 'Firefox',
          browser_version: '60',
          os: 'Windows',
          os_version: '10',
        },
      },
    }),
  );

  return config;
};

Or maybe you want to test only 2 specific browsers?

merge.strategy({
  browsers: 'replace',
})(bsSettings(config), createBaseConfig(config), {
  browserStack: {
    project: 'testing-workflow-for-web-components',
  },
  browsers: [
    'bs_win10_ie_11',
    'bs_win10_firefox_ESR',
  ],
}),

Note: This uses the webpack merge strategies replace.

Quick Recap

Testing is important for every project. Be sure to write as many as you can.
Try to keep your code coverage high, but remember it's not a magic guarantee, so it doesn't always need to be 100%.
Debug in the browser via npm run test:watch. For legacy browsers, use npm run test:legacy.watch.

What's Next?

Run the tests in your CI (works perfectly well together with browserstack). See our recommendations at automating.

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Pascal and Benny for feedback and helping turn my scribbles to a followable story.

Type-Safe Web Components with JSDoc

Thomas Allmer — Thu, 28 Mar 2019 10:03:07 +0000

Writing code is tough and writing it in a way that makes sense to others (or your future self) is even tougher. That's why documentation is a very important part of every software project.

I'm sure we've all found ourselves in the following situation: You're happily coding and just found a nice library that can help you, so you start using it...



import foo from 'foo-lib';

foo.doTheThing(//...

But, did foo.doTheThing() take a string first and then the number or the other way around?

So you head over to http://foo-lib.org and about 5 clicks later you get to the function signature and find out how to use it. First of all, you're already lucky as not many libraries have good documentation 😱

However it already painfully shows that the information is not as close to your workflow as it should be. You have to stop coding and search for the info while it could be directly in your editor. 😊

So we can definitely do better 🤗 Let's get started with a very simple web component.

Note: We will be assuming the editor in use is VS Code.

If you wanna play along - all the code is on github.

<title-bar>



<title-bar>
  #shadow-root (open)
    <h1>You are awesome</h1>
    <div class="dot" style="left: 0px; top: 0px" title="I am dot"></div>
</title-bar>

It's just a little box with a

title property
darkMode property/attribute
formatter function
a sidebar property on the left

We will use LitElement to create it.

Note: We use JavaScript here - but for the most part (except for the type casting & definitions) the example would be the same for TypeScript.



import { LitElement, html, css } from 'lit-element';

export class TitleBar extends LitElement {
  static get properties() {
    return {
      title: { type: String },
      darkMode: { type: Boolean, reflect: true, attribute: 'dark-mode' },
      bar: { type: Object },
    };
  }

  constructor() {
    super();
    this.title = 'You are awesome';
    this.darkMode = false;
    this.bar = { x: 0, y: 0, title: 'I am dot' };
    this.formatter = null;
  }

  render() {
    // positioning the bar like this is just for illustration purposes => do not do this
    return html`
      <h1>${this.format(this.title)}</h1>
      <div
        class="dot"
        style=${`left: ${this.bar.x}px; top: ${this.bar.y}`}
        title=${this.bar.title}
      ></div>
    `;
  }

  format(value) {
    // we'll get to this later
  }

  static get styles() {
    // we'll get to this later
  }
}

customElements.define('title-bar', TitleBar);

What you get when you use it

Let's query our newly created element. 😊



const el = document.querySelector('title-bar');

Here our editor can't know what el actually is so there is no way it can help us in writing better code.
That means no code completion for our own properties even though that information is available.

So what we need to do is cast it:



const el = /** @type {TitleBar} */ (document.querySelector('title-bar'));

Now we already get auto completion. 🎉

However we can still write code like



el.foo = 'bar';
el.title = true;

and nobody will complain.

Let's change that 💪

Add type linting

Add a tsconfig.json file to your project



{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "lib": ["es2017", "dom"],
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": false,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "esModuleInterop": true
  },
  "include": [
    "src",
    "test",
    "node_modules/@open-wc/**/*.js"
  ],
  "exclude": [
    "node_modules/!(@open-wc)"
  ]
}

That is all you need to get VS Code to mark the code as having a problem:



Property 'foo' does not exist on type 'TitleBar'.
Type 'true' is not assignable to type 'string'.

You can even go further by doing the linting in the console and your continuous integration.

All you need to do is:



npm i -D typescript

And add this script to you package.json



  "scripts": {
    "lint:types": "tsc"
  }

Then we can execute it as:



npm run lint:types

This will give you the same error as above but with a filepath and line number.

So just by doing these few extra things your IDE can help you to stay type safe.

Honestly, it will not be a gentle reminder - those red curly lines are hard to ignore and if you need some extra motivation you can hit F8 which will just throw the next error in your face :p.

How does it work?

If you are like me you are probably wondering how does it know what properties are of which type? I certainly did not define any types yet!

Typescript can make a lot of assumptions based on your ES6 code. The actual magic lays in the constructor:



constructor() {
  super();
  this.title = 'You are awesome';
  this.darkMode = false;
  this.bar = { x: 0, y: 0, title: 'I am dot' };
  this.formatter = null;
}

title is obviously a string
darkMode a boolean
bar an object with x, y as number and title a string

So just by defining your initial values within the constructor most of your types should be good to go. 👍
(Don't worry — I did not forget formatter, we'll get to it shortly)

Types are already awesome but we can do even better.

Look at the intellisense in VS Code.

Currently it's really minimal... So let's add some JSDoc:



/**
 * The title to display inside the title bar
 * - should be less then 100 characters
 * - should not contain HTMl
 * - should be between 2-5 words
 *
 * @example
 * // DO:
 * el.title = 'Welcome to the jungle';
 *
 * // DON'T:
 * el.title = 'Info';
 * el.title = 'Welcome to <strong>the</strong> jungle';
 * el.title = 'We like to talk about more then just what sees the eye';
 */
this.title = 'You are awesome';

much better 😊

Note: You do not need to add the @type here as it's clear that it's a string and if you add it - it may get out of sync at some point.

Manually set types

If we look at



this.formatter = null;

There is no way to see from this line alone what the property will hold.
You could assign an empty/default function like



this.formatter = value => `${value}`;

but this does not make sense in all case.
In our example, we would like to skip the formatting if there is no formatter function.
Having a default function would defeat its purpose.
In these cases, it's mandatory to provide a @type and you can do so using JSDoc.



/**
 * You can provide a specific formatter that will change the way the title
 * gets displayed.
 *
 * *Note*: Changing the formatter does NOT trigger a rerender.
 *
 * @example
 * el.formatter = (value) => `${value} for real!`;
 *
 * @type {Function}
 */
this.formatter = null;

That way if you provide a wrong type it will show an error.



el.formatter = false;
// Type 'false' is not assignable to type 'Function'.

Also the immediately appearing @example really makes it easy to create your own formatter.

Setup your own types and use them

There is one more property that doesn't look too nice yet, and that is the bar property.

Our type safety already works here, which is great, but we only know that x is a number; there is no additional info.
We can improve this with JSDocs as well.

So we define a special type called Bar.



/**
 * This is a visible bar that gets displayed at the appropriate coordinates.
 * It has a height of 100%. An optional title can be provided.
 *
 * @typedef {Object} Bar
 * @property {number} x The distance from the left
 * @property {number} y The distance from the top
 * @property {string} [title] Optional title that will be set as an attribute (defaults to '')
 */

Doing so we can also define certain properties as being optional.
The only thing we need to do then is to assign it.



/**
 * @type {Bar}
 */
this.bar = { x: 0, y: 0, title: 'I am dot' };

Add types to function parameters

Let's create a simple format function which will allow for prefix/suffix by default and if you need more you can just override the formatter.

Note: this is not a super useful example but good enough for illustration purposes



format(value = '', { prefix, suffix = '' } = { prefix: '' }) {
  let formattedValue = value;
  if (this.formatter) {
    formattedValue = this.formatter(value);
  }
  return `${prefix}${formattedValue}${suffix}`;
}

Again just by using default options it already knows all the types.

So just adding a little documentation is probably all you need.



/**
 * This function can prefix/suffix your string.
 *
 * @example
 * el.format('foo', { prefix: '...' });
 */
format(value = '', { prefix = '', suffix = '' } = {}) {

Or if you want to have a union type (e.g. allow strings AND numbers).
Be sure to only document what you actually need as with this method you override the default types and that means things could get out of sync.



/**
 * This function can prefix/suffix your string.
 *
 * @example
 * el.format('foo', { prefix: '...' });
 *
 * @param {string|number} value String to format
 */
format(value, { prefix = '', suffix = '' } = {}) {

If you really need to add very specific descriptions to every object options then you need to duplicate the typings.



/**
 * This function can prefix/suffix your string.
 *
 * @example
 * el.format('foo', { prefix: '...' });
 *
 * @param {string} value String to format
 * @param {Object} opts Options
 * @param {string} opts.prefix Mandatory and will be added before the string
 * @param {string} [opts.suffix] Optional and will be added after the string
 */
format(value, { prefix, suffix = '' } = { prefix: '' }) {

Importing Types across files

Files never live in isolation so there might come a point where you want to use a type within another location.
Let's take our good old friend the ToDo List as an example.
You will have todo-item.js & todo-list.js.

The item will have a constructor like this.



constructor() {
  super();
  /**
   * What you need to do
   */
  this.label = '';

  /**
   * How important is it? 1-10
   *
   * 1 = less important; 10 = very important
   */
  this.priority = 1;

  /**
   * Is this task done already?
   */
  this.done = false;
}

So how can I reuse those type in todo-list.js.

Let's assume the following structure:



<todo-list>
  <todo-item .label=${One} .priority=${5} .done=${true}></todo-item>
  <todo-item .label=${Two} .priority=${8} .done=${false}></todo-item>
</todo-list>

and we would like to calculate some statistics.



calculateStats() {
  const items = Array.from(
    this.querySelectorAll('todo-item'),
  );

  let doneCounter = 0;
  let prioritySum = 0;
  items.forEach(item => {
    doneCounter += item.done ? 1 : 0;
    prioritySum += item.prio;
  });
  console.log('Done tasks', doneCounter);
  console.log('Average priority', prioritySum / items.length);
}

The above code actually has an error in it 😱
item.prio does not exists. Types could have saved us here, but how?

First let's import the type



/**
 * @typedef {import('./todo-item.js').ToDoItem} ToDoItem
 */

and then we type cast it.



const items = /** @type {ToDoItem[]} */ (Array.from(
  this.querySelectorAll('todo-item'),
));

And there we already see the type error 💪

Use Data Objects to create Custom Elements

In most cases, we do not only want to access an existing DOM and type cast the result but we would like to actually render those elements from a data array.

Here is the example array



this.dataItems = [
  { label: 'Item 1', priority: 5, done: false },
  { label: 'Item 2', priority: 2, done: true },
  { label: 'Item 3', priority: 7, done: false },
];

and then we render it



return html`
  ${this.dataItems.map(
    item => html`
      <todo-item .label=${item.label} .priority=${item.priority} .done=${item.done}></todo-item>
    `,
  )}
`;

How can we make this type safe?

Unfortunately, simply casting it via @type {ToDoItem[]} does not really work out 😭

It expects the object to be a full representation of an HTMLElement and of course our little 3 property object does miss quite some properties there.

What we can do is to have a Data Representation of our web component. e.g. define what is needed to create such an element in the dom.



/**
 * Object Data representation of ToDoItem
 *
 * @typedef {Object} ToDoItemData
 * @property {string} label
 * @property {number} priority
 * @property {Boolean} done
 */

We can then import and type cast it



/**
 * @typedef {import('./todo-item.js').ToDoItemData} ToDoItemData
 * @typedef {import('./todo-item.js').ToDoItem} ToDoItem
 */

// [...]

constructor() {
  super();
  /**
   * @type {ToDoItemData[]}
   */
  this.dataItems = [
    { label: 'Item 1', priority: 5, done: false },
    { label: 'Item 2', priority: 2, done: true },
    { label: 'Item 3', priority: 7, done: false },
  ];
}

And 🎉 type safety for web component AND its data.

Let your users consume your types

One thing that is a little tougher if you have types not as definition files is how you can make them available.

Generally speaking, you will need to ask your users to add a tsconfig.json like this



{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "node",
    "lib": ["es2017", "dom"],
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "strict": false,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "esModuleInterop": true
  },
  "include": [
    "**/*.js",
    "node_modules/<your-package-name>/**/*.js"
  ],
  "exclude": [
    "node_modules/!(<your-package-name>)"
  ]
}

The important part is the include and not exclude of your package name.

If you think that is a little complicated you are right. There are ideas to improve this flow however it seemed to not have gotten much attention lately - Give it your thumbs up and join the conversation.

For full TypeScript project you might want to do a little more like have 2 tsconfigs.json one for linting and one for buildling (as allowJs prevent automatic creation of definition files).

You can find more details about such an approach at Setup For Typescript on Open Web Components.

Quick recap:

Equipped with these options for properties/functions you should be fine for most web components.

Set defaults for properties in constructor and the type will be there automatically
If you do not have a default make sure to add @types
Add additional information/docs/examples as JSDoc for a nicer developer experience
Make sure to type cast your dom results
Add type linting via console/continuous integration to make sure they are correct
Inform your users how they can consume your types
Bookmark the Typescript JSDoc Reference

If you need more information on additional JSDoc features for types take a look at Type Safe JavaScript with JSDoc. I highly recommend reading it!

The full code can be found on github.
To see how your users will get it look at the tests.

What's next?

These are steps that can help make web components simpler and saver to use.
Not everything here is useful for every situation and there will be definitely situations where we don't have a recipe yet.
If you encounter any issues (hopefully + solution) please let us know and we will add it to this "Cookbook for types with web components".
VS Code is working on making a way to bring autocomplete to declarative html by having a definition for web components attribute - See the proposal to allow for getting errors if undefined attributes are used: ```



Follow me on [Twitter](https://twitter.com/daKmoR).
If you have any interest in web component make sure to check out [open-wc.org](https://open-wc.org).

DEV Community: Thomas Allmer

Introducing check html links - no more bad links

Evaluation and the decision for a new tool

Focusing on Useful Output

Error in File Focused

Missing File Focused

A clear winner

Focusing on Speed

Being part of the NodeJS ecosystem

Focusing on a small Dependency Tree

Solution

Usage

Usage Github Action

Comparison

Future

Acknowledgements

Introducing mdjs - interactive demos everywhere

For tools that do not run in the browser

For (visual) components that do run in the browser

Vue

React

Limitations

Introducing Markdown with JavaScript (mdjs)

Enhancing mdjs with demo format

mdjs default docs page

Where can you use mdjs?

You can use it locally via es-dev-server

You can use it via Storybook

Show it on github

Supported on webcomponents.dev

How you can add support for mdjs

Resume

Future

Acknowledgements

Using JavaScript Mixins The Good Parts

What is a Mixin?

Why is Deduping of Mixins Necessary?

Nested examples

When NOT to use a Mixin

I want to do if (this.isIE11()) { // ... }

I want to have a special this.addEventListener()

When to use a Mixin

What we have learned

Notes

ING open sources Lion: A library of performant, accessible & flexible Web Components

Why Lion?

Framework Agnostic

Customize Functionality

Accessibility

Summary

What can we do to tackle these issues?

What is Lion?

White Label

🎯 Focus

Lessons learned

🙋‍ Join us!

Adopt Lion!

Contribute to Lion!

🔨 Extend the components

Why Open Source?

But there's more!

Thanks

Storybook for web components on steroids

Excursion universal demo system

Two builds (continued)

Excursion shipping code based on browser capabilities

Source maps

Opportunity

Storybook on steroids

Prebuild storybook

Replace webpack magic

Mimic how the preview communicates with the manager

Extra mdx support

Use rollup to build a static storybook

Verdict

Future

Acknowledgements

Generating TypeScript Definition Files from JavaScript

Examples in TypeScript

Achieving Type Safety in Vanilla JavaScript

I want to do `if (this.isIE11()) { // ... }`

I want to have a special `this.addEventListener()`