One of the most common topics that comes up as part of this is “dependency bloat” - the idea that npm dependency trees are getting larger over time, often with long since redundant code which the platform now provides natively.

In this post, I want to briefly look at what I think are the three main types of bloat in our dependency trees, why they exist, and how we can start to address them.

1. Older runtime support (with safety and realms)

The graph above is a common sight in many npm dependency trees - a small utility function for something which seems like it should be natively available, followed by many similarly small deep dependencies.

So why is this a thing? Why do we need is-string instead of typeof checks? Why do we need hasown instead of Object.hasOwn (or Object.prototype.hasOwnProperty)? Three things:

1. Support for very old engines
2. Protection against global namespace mutation
3. Cross-realm values

Support for very old engines

Somewhere in the world, some people apparently exist who need to support ES3 - think IE6/7, or extremely early versions of Node.js.¹

For these people, much of what we take for granted today does not exist. For example, they don’t have any of the following:

• Array.prototype.forEach
• Array.prototype.reduce
• Object.keys
• Object.defineProperty

These are all ES5 features, meaning they simply don’t exist in ES3 engines.

For these unfortunate souls who are still running old engines, they need to reimplement everything themselves, or be provided with polyfills.

Alternatively, what’d be really nice is if they upgraded.

Protection against global namespace mutation

The second reason for some of these packages is “safety”.

Basically, inside Node itself, there is a concept of “primordials”. These are essentially just global objects wrapped at startup and imported by Node from then on, to avoid Node itself being broken by someone mutating the global namespace.

For example, if Node itself uses Map and we re-define what Map is - we can break Node. To avoid this, Node keeps a reference to the original Map which it imports rather than accessing the global.

You can read more about this here in the Node repo.

This makes a lot of sense for an engine, since it really shouldn’t fall over if a script messes up the global namespace.

Some maintainers also believe this is the correct way to build packages, too. This is why we have dependencies like math-intrinsics in the graph above, which basically re-exports the various Math.* functions to avoid mutation.

Cross-realm values

Lastly, we have cross-realm values. These are basically values you have passed from one realm to another - for example, from a web page to a child <iframe> or vice versa.

In this situation, a new RegExp(pattern) in an iframe, is not the same RegExp class as the one in the parent page. This means window.RegExp !== iframeWindow.RegExp, which of course means val instanceof RegExp would be false if it came from the iframe (another realm).

For example, I am a maintainer of chai, and we have this exact issue. We need to support assertions happening across realms (since a test runner may run tests in a VM or iframe), so we can’t rely on instanceof checks. For that reason, we use Object.prototype.toString.call(val) === '[object RegExp]' to check if something is a regex, which works across realms since it doesn’t rely on the constructor.

In the graph above, is-string is basically doing this same job in case we passed a new String(val) from one realm to another.

Why this is a problem

All of this makes sense for a very small group of people. If you’re supporting very old engines, passing values across realms, or want protection from someone mutating the environment - these packages are exactly what you need.

The problem is that the vast majority of us don’t need any of this. We’re running a version of Node from the last 10 years, or using an evergreen browser. We don’t need to support pre-ES5 environments, we don’t pass values across frames, and we uninstall packages which break the environment.²

These layers of niche compatibility somehow made their way into the “hot path” of everyday packages. The tiny group of people who actually need this stuff should be the ones seeking out special packages for it. Instead, it is reversed and we all pay the cost.

2. Atomic architecture

Some folks believe that packages should be broken up to an almost atomic level, creating a collection of small building blocks which can later be re-used to build other higher level things.

This kind of architecture means we end up with graphs like this:

As you can see, the most granular snippets of code have their own packages. For example, shebang-regex is the following at the time of writing this post:

const shebangRegex = /^#!(.*)/;
export default shebangRegex;

By splitting code up to this atomic level, the theory is that we can then create higher level packages simply by joining the dots.

Some examples of these atomic packages to give you an idea of the granularity:

• arrify - Converts a value to an array (Array.isArray(val) ? val : [val])
• slash - Replace backslashes in a file-system path with /
• cli-boxes - A JSON file containing the edges of a box
• path-key - Get the PATH environment variable key for the current platform (PATH on Unix, Path on Windows)
• onetime - Ensure a function is only called once
• is-wsl - Check if process.platform is linux and os.release() contains microsoft
• is-windows - Check if process.platform is win32

If we wanted to build a new CLI for example, we could pull a few of these in and not worry about implementation. We don’t need to do env['PATH'] || env['Path'] ourselves, we can just pull a package for that.

Why this is a problem

In reality, most or all of these packages did not end up as the reusable building blocks they were meant to be. They’re either largely duplicated across various versions in a wider tree, or they’re single-use packages which only one other package uses.

Single use packages

Let’s take a look at some of the most granular packages:

• shebang-regex is used almost solely by shebang-command by the same maintainer
• cli-boxes is used almost solely by boxen and ink by the same maintainer
• onetime is used almost solely by restore-cursor by the same maintainer

Each of these having only one consumer means they’re equivalent of inline code but cost us more to acquire (npm requests, tar extraction, bandwidth, etc.).

Duplication

Taking a look at nuxt’s dependency tree, we can see a few of these building blocks duplicated:

• is-docker (2 versions)
• is-stream (2 versions)
• is-wsl (2 versions)
• isexe (2 versions)
• npm-run-path (2 versions)
• path-key (2 versions)
• path-scurry (2 versions)

Inlining them doesn’t mean we no longer duplicate the code, but it does mean we don’t pay the cost of things like version resolution, conflicts, cost of acquisition, etc.

Inlining makes duplication almost free, while packaging makes it expensive.

Larger supply chain surface area

The more packages we have, the larger our supply chain surface area is. Every package is a potential point of failure for maintenance, security, and so on.

For example, a maintainer of many of these packages was compromised last year. This meant hundreds of tiny building blocks were compromised, which meant the higher level packages we actually install were also compromised.

Logic as simple as Array.isArray(val) ? val : [val] probably doesn’t need its own package, security, maintenance, and so on. It can just be inlined and we can avoid the risk of it being compromised.

Similar to the first pillar, this philosophy made its way into the “hot path” and probably shouldn’t have. Again, we all pay the cost to no real benefit.

3. “Ponyfills” that overstayed their welcome

³

If you’re building an app, you might want to use some “future” features your chosen engine doesn’t support yet. In this situation, a polyfill can come in handy - it provides a fallback implementation where the feature should be, so you can use it as if it were natively supported.

For example, temporal-polyfill polyfills the new Temporal API so we can use Temporal regardless of if the engine supports it or not.

Now, if you’re building a library instead, what should you do?

In general, no library should load a polyfill as that is a consumer’s concern and a library shouldn’t be mutating the environment around it. As an alternative, some maintainers choose to use what’s called a ponyfill (sticking to the unicorns, sparkles and rainbows theme).

A ponyfill is basically a polyfill you import rather than one which mutates the environment.

This kinda works since it means a library can use future tech by importing an implementation of it which passes through to the native one if it exists, and uses the fallback otherwise. None of this mutates the environment, so it is safe for libraries to use.

For example, fastly provides @fastly/performance-observer-polyfill, which contains both a polyfill and ponyfill for PerformanceObserver.

Why this is a problem

These ponyfills did their job at the time - they allowed the library author to use future tech without mutating the environment and without forcing the consumer to know which polyfills to install.

The problem comes when these ponyfills outstay their welcome. When the feature they fill in for is now supported by all engines we care about, the ponyfill should be removed. However, this often doesn’t happen and the ponyfill remains in place long after it’s needed.

We’re now left with many, many packages which rely on ponyfills for features we’ve all had for a decade now.

For example:

• globalthis - ponyfill for globalThis (widely supported in 2019, 49M downloads a week)
• indexof - ponyfill for Array.prototype.indexOf (widely supported in 2010, 2.3M downloads a week)
• object.entries - ponyfill for Object.entries (widely supported in 2017, 35M downloads a week)

Unless these packages are being kept alive because of Pillar 1, they’re usually still used just because nobody ever thought to remove them.

When all long-term support versions of engines have the feature, the ponyfill should be removed.⁴

What can we do about it?

Much of this bloat is so deeply nested in dependency trees today that it is a fairly hefty task to unravel it all and get to a good place. It will take time, and it will take a lot of effort from maintainers and consumers.

Having said that, I do think we can make significant progress on this front if we all work together.

Start asking yourself, “why do I have this package?” and “do I really need it?”.

If you find something which seems redundant, raise an issue with the maintainer asking if it can be removed.

If you encounter a direct dependency which has many of these issues, have a look for an alternative which doesn’t. A good start for that is the module-replacements project.

Using knip to remove unused dependencies

knip is a great project which can help you find and remove unused dependencies, dead code, and much more. In this case, it can be a great tool to help you find and remove dependencies you no longer use.

This doesn’t solve the problems above necessarily, but is a great starting point to help clean up the dependency tree before doing more involved work.

You can read more about how knip deals with unused dependencies in their documentation.

Using the e18e CLI to detect replaceable dependencies

The e18e CLI has a super useful analyze mode to determine which dependencies are no longer needed, or have community recommended replacements.

For example, if you get something like this:

$ npx @e18e/cli analyze

...

│  Warnings:
│    • Module "chalk" can be replaced with native functionality. You can read more at
│      https://nodejs.org/docs/latest/api/util.html#utilstyletextformat-text-options. See more at
│      https://github.com/es-tooling/module-replacements/blob/main/docs/modules/chalk.md.

...

Using this, we can quickly identify which direct dependencies can be cleaned up. We can also then use the migrate command to automatically migrate some of these dependencies:

$ npx @e18e/cli migrate --all

e18e (cli v0.0.1)

┌  Migrating packages...
│
│  Targets: chalk
│
◆  /code/main.js (1 migrated)
│
└  Migration complete - 1 files migrated.

In this case, it will migrate from chalk to picocolors, a much smaller package which provides the same functionality.

In the future, this CLI will even recommend based on your environment - for example, it could suggest the native styleText instead of a colours library if you’re running a new enough Node.

Using npmgraph to investigate your dependency tree

npmgraph is a great tool to visualize your dependency tree and investigate where bloat is coming from.

For example, let’s take a look at the bottom half of ESLint’s dependency graph as of writing this post:

We can see in this graph that the find-up branch is isolated, in that nothing else uses its deep dependencies. For something as simple as an upwards file-system traversal, maybe we don’t need 6 packages. We can then go look for an alternative, such as empathic which has a much smaller dependency graph and achieves the same thing.

Module replacements

The module replacements project is being used as a central data set for the wider community to document which packages can be replaced with native functionality, or more performant alternatives.

If you’re ever in need of an alternative or just want to check your dependencies, this data set is great for that.

Similarly, if you come across packages in your tree which are made redundant by native functionality, or just have better battle-tested alternatives, this project is definitely a great place to contribute that so others can benefit from it.

Paired with the data, there’s also a codemods project which provides codemods to automatically migrate some of these packages to their suggested replacements.

Closing Thoughts

We all pay the cost for an incredibly small group of people to have an unusual architecture they like, or a level of backwards compatibility they need.

This isn’t necessarily a fault of the people who made these packages, as each person should be able to build however they want. Many of them are an older generation of influential JavaScript developers - building packages in a darker time where many of the nice APIs and cross-compatibility we have today didn’t exist. They built the way they did because it was possibly the best way at the time.

The problem is that we never moved on from that. We still download all of this bloat today even though we’ve had these features for several years.

I think we can solve this by reversing things. This small group should pay the cost - they should have their own special stack pretty much only they use. Everyone else gets the modern, lightweight, and widely supported code.

Hopefully things like e18e and npmx can help with that through documentation, tooling, etc. You can also help by taking a closer look at your dependencies and asking “why?”. Raise issues with your dependencies asking them if, and why they need these packages anymore.

We can fix it.

Footnotes

I think we’ve ended up with many libraries in our ecosystem which are edge-case-first, the opposite to what I’d expect. I’ll give a few examples and some thoughts around this, mostly in the hope we can start to trim some of it away.

The problem

I believe a lot of the questionably small libraries hiding in our deep dependency trees are a result of over-engineering for inputs and edge cases we’ve probably never seen.

For example, say we’re building a clamp function:

export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max);
}

Pretty simple!

What if someone passes nonsensical ranges? Let’s handle that.

export function clamp(value: number, min: number, max: number): number {
  if (min > max) {
    throw new Error('min must be less than or equal to max');
  }
  return Math.min(Math.max(value, min), max);
}

This is probably as far as I’d go. But let’s over-engineer - what if someone passes a number-like string?

export function clamp(value: number | string, min: number | string, max: number | string): number {
  if (typeof value === 'string' && Number.isNaN(Number(value))) {
    throw new Error('value must be a number or a number-like string');
  }
  if (typeof min === 'string' && Number.isNaN(Number(min))) {
    throw new Error('min must be a number or a number-like string');
  }
  if (typeof max === 'string' && Number.isNaN(Number(max))) {
    throw new Error('max must be a number or a number-like string');
  }
  if (Number(min) > Number(max)) {
    throw new Error('min must be less than or equal to max');
  }
  return Math.min(Math.max(value, min), max);
}

At this point, it seems clear to me we’ve just poorly designed our function. It solely exists to clamp numbers, so why would we accept strings?

But hey, let’s go further! What if other libraries also want to accept such loose inputs? Let’s extract this into a separate library:

import isNumber from 'is-number';

export function clamp(value: number | string, min: number | string, max: number | string): number {
  if (!isNumber(value)) {
    throw new Error('value must be a number or a number-like string');
  }
  if (!isNumber(min)) {
    throw new Error('min must be a number or a number-like string');
  }
  if (!isNumber(max)) {
    throw new Error('max must be a number or a number-like string');
  }
  if (Number(min) > Number(max)) {
    throw new Error('min must be less than or equal to max');
  }
  return Math.min(Math.max(value, min), max);
}

Whoops! We’ve just created the infamous is-number library!

How it should be

This, in my opinion, is poor technical design we’ve all ended up dealing with over the years. Carrying the baggage of these overly-granular libraries that exist to handle edge cases we’ve probably never encountered.

I think it should have been:

export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max);
}

Maybe with some min <= max validation, but even that is debatable. At this point, you may as well inline the Math.min(Math.max(...)) expression instead of using a dependency.

We should be able to define our functions to accept the inputs they are designed for, and not try to handle every possible edge case.

There are two things at play here:

• Data types
• Values

A well designed library would assume the right data types have been passed in, but may validate that the values make sense (e.g. min is less than or equal to max).

These over-engineered libraries have decided to implement both at runtime - essentially run-time type checking and value validation. One could argue that this is just a result of building in the pre-TypeScript era, but that still doesn’t justify the overly specific value validation (e.g. the real is-number also checks that it is finite).

What we shouldn’t do

We shouldn’t build edge-case-first libraries, i.e. those which solve for edge cases we have yet to encounter or are unlikely to ever encounter.

Example: is-arrayish (76M downloads/week)

The is-arrayish library determines if a value is an Array or behaves like one.

There will be some edge cases where this matters a lot, where we want to accept something we can index into but don’t care if it is a real Array or not.

However, the common use case clearly will not be that and we could’ve just used Array.isArray() all along.

Example: is-number (90M downloads/week)

The is-number library determines if a value is a positive, finite number or number-like string (maybe we should name it is-positive-finite-number to be more accurate).

Again, there will be edge cases where we want to deal with number-like strings or we want to validate that a number is within a range (e.g. finite).

The common use case will not be this. The common use case will be that we want to check typeof n === 'number' and be done with it.

For those edge cases where we want to additionally validate what kind of number it is, we could use a library (but one which exists for the validation, not for the type check).

Example: pascalcase (9.7M downloads/week)

The pascalcase library transforms text to PascalCase.

It has 1 dependency (camelcase) and accepts a variety of input types:

• strings
• null
• undefined
• arrays of strings
• functions
• arbitrary objects with toString methods

In reality, almost every user will be passing a string.

Example: is-regexp (10M downloads/week)

The is-regexp library checks if a value is a RegExp object, and supports cross-realm values.

In reality, almost every user will be passing a RegExp object, and not one from another realm.

For context, cross-realm values can happen when you retrieve a value from an iframe or VM for example:

const iframe = document.createElement('iframe');
iframe.contentWindow.RegExp === RegExp; // false

const iframeRegex = iframe.contentWindow.someRegexp;

iframeRegex instanceof RegExp; // false
isRegex(iframeRegex); // true

This is indeed useful, and I do support this myself in chai (which I maintain). However, this is an edge case most libraries don’t need to care about.

What we should do

We should build libraries which solve the common use case and make assumptions about the input types they will be given.

Example: scule (1.8M downloads/week)

scule is a library for transforming casing of text (e.g. camel case, etc).

It only accepts inputs it is designed for (strings and arrays of strings) and has zero dependencies.

In most of the functions it exports, it assumes valid input data types.

Example: dlv (14.9M downloads/week)

dlv is a library for deep property access.

It only accepts strings and arrays of strings as the path to access, and assumes this (i.e. does no validation).

Validation is important

Validation is important, and I want to be clear that I’m not saying we should stop validating our data.

However, we should usually be validating the data in the project that owns it (e.g. at the app level), and not in every library that later consumes it as input.

Deep dependencies applying validation like this actually shift the burden from where it belongs (at data boundaries) to deep in the dependency tree.

Often at this point, it is invisible to the consumer of the library.

How many people are passing values into is-number (via other libraries), not realising it will prevent them from using negative numbers and Infinity?

A note on overly-granular libraries

This post isn’t about overly-granular libraries in general, but I’d like to briefly mention them for visibility.

An overly-granular library is one where someone took a useful library and split it up into an almost atomic-level of granularity.

Some examples:

• shebang-regex - 2LOC, does the same as startsWith('#!'), 86M downloads/week
• is-whitespace - 7LOC, checks if a string is only whitespace, 1M downloads/week
• is-npm - 8LOC, checks npm_config_user_agent or npm_package_json are set, 7M downloads/week

This is a personal preference some maintainers clearly prefer. The thought seems to be that by having atomic libraries, you can easily build your next library mostly from the existing building blocks you have.

I don’t really agree with this and think downloading a package for #! 86 million times a week is a bit much.

What can be done about this?

The e18e community is already tackling a lot of this by contributing performance improvements across the ecosystem, including removing and replacing dependencies with more modern, performant ones.

Through these efforts, there’s already a useful list of replacements and an ESLint plugin.

As a maintainer

If you’re maintaining a library, it would be worth reviewing your dependencies to see if:

• Any are replaceable by native functionality these days (e.g. Array.isArray)
• Any are replaceable by smaller, less granular and/or more performant alternatives (e.g. scule instead of pascalcase)
• Any are redundant if you make more assumptions about input types

Tools like npmgraph can help you visualise your dependency tree to make this task easier.

Also, being stricter around input types will allow you to reduce a lot of code and dependencies.

If you can assume the data being passed in is the correct type, you can leave validation up to the consumer.

As a user

Keep a close eye on your dependencies (both deep and direct), and what alternatives are available to your direct dependencies.

Often, it is easy to stick with a dependency from long ago and forget to re-visit it one day in case there is a better way. Many of these packages are possible natively, or have more modern alternatives.

Useful tools:

• npmgraph for visualising your dependency tree
• node-modules.dev for visualising your dependencies and lots of useful meta data
• Dependabot for keeping your dependencies up to date

On the topic of data, it is also worth ensuring validation happens at data boundaries rather than being delegated to various dependencies. Try to validate the type and value up front, before passing into dependencies.

Conclusion

Most of these libraries exist to handle edge cases that do certainly exist. However, we are all paying the cost of that rather than only those who need to support those edge cases.

This is the wrong way around. Libraries should implement the main use case, and alternatives (or plugins) can exist to provide the edge cases the minority needs.

We should all be more aware of what is in our dependency tree, and should push for more concise, lighter libraries.

Leaving my job

I had a pretty fun job as an engineering lead/principal with a really awesome team alongside me. It gave me many opportunities to mentor people in the areas I love, and introduce so many engineers to things I care about a lot (like web components and web standards).

However, I’ve always loved travelling and had an itch in my brain for a long time now, wanting to head in some random direction for a few months and see more of the world.

In the end, I decided I’ve learnt what I can learn at my job, making now the perfect time to finally go do that!

Travelling

I’m already pretty well travelled and have done countless solo trips over many years. Combine that with the fact I’m happy without much of a plan, I pretty much had to choose a direction and head that way.

I decided on a few things:

• Aim to head East until I’m back home (i.e. go all the way around)
• Spend half of the trip exploring, half of it meeting up with friends I haven’t seen in a while
• Start with a Europe trip, somehow reach Vietnam, and figure the rest out from there

It is worth noting that I did actually come back to the UK for a week after the Europe portion of the trip (for arctangent festival!).

I planned most of my travel days only a day or two before, but I did have a shortlist of cities I wanted to try reach for the second half of my trip (since I wanted to meet up with specific people).

In the end, these are the countries I visited:

• Belgium
• Germany
• Austria
• Hungary (where I finally got to hang out with @patak.dev!)
• Czech Republic
• Poland
• Vietnam
• Japan
• Singapore
• Philippines
• Australia
• New Zealand
• USA (including good catch ups with @marcushellberg.dev and a few of the @lit.dev team)
• Canada

From Canada, I also did a small detour to Germany to see some friends I made in Vietnam and visit some Christmas markets. Great fun!

Overall, good trip. Made a lot of new friends, visited a few old friends, and saw a lot of really awesome places.

Open source

One of the perks of having no job (for now) is that I have a bunch more time to spend on my open source efforts!

This came at the ideal time, as we’d just launched the e18e community. Being able to spend more time on that, especially during the growing phase, has been super nice.

I’ve been able to work with so many like-minded people on all sorts of performance improvements across the ecosystem. Not only cleanups, but deep dives into CPU and memory profiles and much more.

We can’t forget, though, that I maintain and contribute to a whole bunch of projects already. So I’ve basically been splitting my time between those (e.g. chai, tinylibs, chokidar) and e18e.

This has been quite a lot of work but so much fun at the same time. Focusing on the things I care about and providing a whole bunch of useful things for the community.

What’s next?

I’ll be focusing a lot on e18e still, trying to help grow the community and have a larger effect on the performance of the tools and web apps we all use.

I have no idea what work I will end up in next, but I’ll always manage to cut a chunk of time out for my OSS efforts.

Of course, I’ll probably also end up travelling again now that I’ve got the bug!

These are just a few tips from what I found.

The aim

It is common that we might want to emit custom events from our components. For example:

class MyElement extends HTMLElement {
  // ..
  protected _doSomething(): void {
    this.dispatchEvent(new CustomEvent('my-event'));
  }
}

In these situations, a consumer of the component would listen like so:

node.addEventListener('my-event', (ev) => {
  // ...
});

However, there would be no helpful type information to suggest that my-event is a valid (“known”) event and the type of the event it is.

So our aim to strengthen this would be to strongly type those events and give editors better completion/information.

Event maps

Thankfully, TypeScript already helped solve this problem with “event maps”. These are basically interfaces to hold the names of events and their type.

You can see that addEventListener is roughly typed like so:

// example map
interface EventMap {
  'my-event': MyCustomEventType;
}

// method
addEventListener<T extends keyof EventMap>(
  type: T,
  listener: (event: EventMap[T]) => any
);

Where EventMap is one of a few available maps depending on the type of node you’re dealing with.

The fall back, for when it isn’t in the event map, is basically Event. This means we’re not too strict.

Anyhow this results in useful hints and types like so:

document.addEventListener('load', fn); // knows that 'load' is an event
node.addEventListener('blur', (ev) => { ... }); // knows `ev` is `FocusEvent`
node.addEventListener('doesntexist', (ev) => { ... }); // `ev` is `Event`

Built in event maps

There are several, a couple are:

• DocumentEventMap - defines all events available to Document
• WindowEventMap - defines all events available to Window
• HTMLElementEventMap - defines all events available to any HTML element

Extending a built in map

You can extend a built in event map by augmenting the global interface:

declare global {
  interface WindowEventMap {
    'my-event': CustomEvent<{foo: number}>;
  }
}

// ...

window.addEventListener(
  'my-event', // will be a known event name, suggested in your editor
  (ev) => { // will be typed as `CustomEvent<{foo: number}>`
    ev.detail.foo; // number
  }
);

Defining your own event maps

You may want to tie events to your component and only your component, rather than the globally available list of events.

To do this, you can re-define addEventListener:

interface MyEventMap {
  'my-event': CustomEvent<{foo: number}>;
}

class MyElement extends HTMLElement {
  public addEventListener<T extends keyof MyEventMap>(
    // the event name, a key of MyEventMap
    type: T,

    // the listener, using a value of MyEventMap
    listener: (this: MyElement, ev: MyEventMap[T]) => any,

    // any options
    options?: boolean | AddEventListenerOptions
  ): void;

  // the fallback for any event names not in our map
  public addEventListener(
    type: string,
    listener: (this: MyElement, ev: Event) => any,
    options?: boolean | AddEventListenerOptions
  ): void {
    super.addEventListener(type, listener, options);
  }
}

// ...

const node = document.createElement('my-element');
node.addEventListener(
  'my-event', // strongly typed, suggested by editor
  (ev) => { ... } // ev is a `CustomEvent<{foo: number}>`
);

It looks like there’s a lot going on here, but really we are just copying what the original definition of addEventListener is from TypeScript’s DOM definitions.

Wrap up

Again, this was just a quick one to show the findings. These things can make the dev experience super nice, though.

Now in our editors we can get strongly typed event names along with their strongly typed events, rather than relying on casts and what not.

stylelint + lit-element = good times

As some of you know, lately I’ve been very much involved in a few linting projects as well as spending plenty of time contributing to the linters themselves.

One thing I’ve been missing so far in my own projects is the ability to lint my CSS so I can easily enforce best practices and, more importantly, detect potential problems in my rules/syntax.

This has been possible in projects which use CSS as-is for some time, using the excellent open source stylelint.

However, it has been a bit of a struggle when using a project like lit-element due to the fact that most or all stylesheets are contained within template literals (for several reasons I won’t go into here).

A PR or two recently got merged, though, so it is no longer such a struggle!

A lit element

Here’s an example element which uses lit, so you get an idea of how a stylesheet might look in this case:

class FooElement extends LitElement {
  static get styles() {
    return css`
      :host { display: block; }
    `;
  }

  render() {
    return html`<h1>I'm some content!</h1>`;
  }
}

The problem & solution

As mentioned before, the problem here is that the styles exist inside a template literal rather than an actual stylesheet (i.e. a css file).

Due to this, stylelint can’t lint it out of the box as it has no idea how to extract the CSS.

Here is where the very useful stylelint-processor-styled-components processor comes in handy and can be gently pushed to into supporting our needs.

This handy little processor allows stylelint to extract CSS from styled-components which look a bit like this:

const MyTitle = styled.h1`
  color: hotpink;
`;

// This is rendered with hotpink color
<MyTitle>Some Title</MyTitle>

Looks familiar, right? If only we could tell the processor to look for css templates rather than styled templates, right??

We’re in luck! This processor allows you to define which module and which import name to extract CSS from with a bit of config:

{
  "importName": "css",
  "moduleName": "lit-element",
  "strict": true
}

Each of these has the following meaning:

• importName specifies which function to parse template strings for
• moduleName specifies which module the function we specified must be imported from (to avoid parsing non-lit css functions)
• strict specifies that we only want to parse this specific import from the module we specified

The strict flag is a recent addition from me. I added it because the processor’s default behaviour is to extract CSS from all lit-element imports, which means it will try (and fail…) to lint html contents too. This flag pretty much enables a little stricter parsing so only the named import is parsed.

Setup

So this’ll be fairly straight forward!

Install

$ npm i -D stylelint
  stylelint-processor-styled-components
  stylelint-config-recommended
  stylelint-config-styled-components

Configure

Create a .stylelintrc.json:

{
  "processors": [
    [
      "stylelint-processor-styled-components",
      {
        "moduleName": "lit-element",
        "importName": "css",
        "strict": true
      }
    ]
  ],
  "extends": [
    "stylelint-config-recommended",
    "stylelint-config-styled-components"
  ]
}

Simple. We enable the processor, then we tell it to only parse CSS from lit-element’s css template function and we extend the provided configs to do some bits of leg work for us.

Run it!

$ npx stylelint "src/**/*.js"

Add it to your package.json as a script, too, to make things a little easier:

{
  "scripts": {
    "lint:css": "stylelint \"src/**/*.js\""
  }
}

Wrap up

I was stuck for quite some time having literally no clue how on earth I lint some “pseudo-CSS” from inside some template expression. A few people seemed to be in the same situation, so I hope this helped you out and gave a good idea of the direction to head in.

Don’t forget to try out a code formatter too, such as prettier! You should totally make use of something like this instead of relying on stylistic lint rules.

I had such crazily customised lint rules until I came to the revelation that I just need to format code automatically instead of relying on mere humans. Now our development process is much smoother, highly recommended.

Anyhow, enjoy becoming as much of a pain as I am with my error-level max line length and JSDoc rules :x

Recently, though, TSLint announced that they were now going to work on the convergence of the two projects.

This is great news! However, some things should be cleared up and an example of how we should now be linting our projects would be useful…

ESLint already supported TypeScript for some time

ESLint has supported TypeScript for quite some time through its typescript-eslint plugin and parser.

Quite a few people have asked me what they should do until TSLint “converges” with ESLint. The answer is pretty much that they already converged, long ago. TSLint’s blog post was a little unclear here, but do understand you can already lint your TypeScript without TSLint.

ESLint rules can still be used

TSLint wasn’t the best approach to linting TypeScript, in my opinion. The correct solution was the one we’re now seeing: building support into the linter everyone else already uses.

Due to TSLint’s standalone approach, it meant you couldn’t use any of your usual ESLint rules and plugins but rather could only use their built in ones.

Now that you can use ESLint’s own TypeScript support, it means you can use any other ESLint rules and plugins in addition to your TypeScript rules.

ESLint is still a little behind

Unfortunately, not all TypeScript-specific rules in ESLint make full use of the TypeScript type system yet. Commonly, they operate on the JS after transpilation has happened so some information can be lost.

Part of TSLint’s contributions (and plenty of other people already contributing to this) will be to add type-system knowledge to the rules so much stronger assertions can be built.

This’ll change/improve very soon as rules are already beginning to make use of the type system.

Using ESLint on TypeScript today

Install:

$ npm i -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Configure .eslintrc.json:

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "env": {
    "browser": true
  },
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2017,
    "sourceType": "module"
  },
  "plugins": [
    "@typescript-eslint/eslint-plugin"
  ],
  "rules": {
  }
}

Run:

$ eslint "src/**/*.ts"

Easy as that!

Recommendations

Choose compilation options over lint rules

You should usually choose compilation checks which the TypeScript compiler handles rather than relying on the looser lint rules.

In particular, disable the @typescript-eslint/no-unused-vars rule and use the following options in your tsconfig.json instead:

{
  "compilerOptions": {
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "strict": true // This is useful too, to enable several strict checks
  }
}

Naming conventions

Another useful one is member naming conventions:

{
  "rules": {
    "@typescript-eslint/member-naming": ["error", {
      "private": "^__",
      "protected": "^_"
    }]
  }
}

This will enforce a convention many people already follow:

• Private members begin with __
• Protected members begin with _

With the introduction of private class fields coming soon, this may well become redundant in future so use it as you feel best.

It is more of a personal preference.

Use a code formatter instead of stylistic rules

I’ve tried having very strict lint rules for formatting, checking things like indentation, spacing and trailing commas.

It always results in a painful development process unless you just happen to have a personal preference for the exact same style. This is of course very unlikely as we all have our own opinion.

A much better solution is to disable all formatting related lint rules and instead use a formatter.

Two I use are:

• prettier
• clang-format

I’m gradually moving towards prettier, I think, but both generally do a good job (and offer different styles so it is far from “which is best?”).

I use the following .prettierrc:

---
bracketSpacing: false
printWidth: 80
semi: true
singleQuote: true
tabWidth: 2
useTabs: false
arrowParens: always

I use the following .clang-format:

BasedOnStyle: Google
AlignAfterOpenBracket: AlwaysBreak
AllowAllParametersOfDeclarationOnNextLine: false
AllowShortBlocksOnASingleLine: false
AllowShortCaseLabelsOnASingleLine: false
AllowShortFunctionsOnASingleLine: None
AllowShortIfStatementsOnASingleLine: false
AllowShortLoopsOnASingleLine: false
BinPackArguments: false

Generally, ESLint will play nicely with both of these as long as you remembered to turn off any stylistic rules.

Use a .editorconfig file

One last thing which isn’t so much ESLint related is something I’d just like to see people do more often.

Get into the habit of introducing a .editorconfig file like so:

[*]
end_of_line = lf
indent_size = 2
indent_style = space
trim_trailing_whitespace = true

This makes your codebase much easier to edit by other people while maintaing the same whitespace and indentation rules.

Almost all editors support this out of the box.

One of these rules was no-any.

While this does mean everyone now hates me, it has also lead to people on these projects learning and understanding the type system of TypeScript much more than they previously did.

So here’s a few things we learnt by avoiding the any type…

It isn’t bad

The any type isn’t necessarily a bad thing and, in actual fact, does still come in useful sometimes. However, in most cases, there is a better alternative that leads to having better defined types overall.

Anyhow, with that out of the way…

unknown can usually be used instead

The unknown type is relatively new, introduced in TypeScript 3.0.

It is similar to any in that it can be “anything”, but has one huge difference: it can only be interacted with once we know the type (through something like a type guard or inference).

A quick example:

const foo: any = "foo";
const bar: unknown = "bar";

foo.length; // Works, type checking is effectively turned off for this
bar.length; // Errors, bar is unknown

if (typeof bar === 'string') {
  bar.length; // Works, we now know that bar is a string
}

In most cases, you can do the ol’ switcheroo and unknown will work fine where you once had any. Just be ready for a painful fair amount of changes needed to add type guards or casts throughout your code…

Record can be used for basic objects

A common thing i’ve seen is the use of any in parsing API responses (e.g. JSON) as the type of the objects may not always be known.

More than likely, such objects are… objects. So give Record a try instead:

const foo: any = { a: 1, b: 2 };
const bar: Record<string, number> = { a: 1, b: 2};

foo.a; // Anything
bar.a; // Number

const obj = JSON.parse(response) as Record<string, unknown>[];
obj[0].id; // unknown but we can at least access it correctly

As you can see, it can work well to combine this with unknown too if you have more complex objects and you’ll at least have better than any.

Explicit types are easier to understand and read

This is more about types in general than just any, but we often had cases like this:

function doSomething(obj: Model) {
  if (obj.x) {
    return doAnotherThing(obj);
  }
  if (obj.y) {
    return obj.y;
  }
  return null;
}

This isn’t a great example, but it is already difficult from a glance at the function to know what it returns.

If we instead had:

function doSomething(obj: Model): XModel|YModel|null {

It is much clearer. This also applies to non-obvious variables and anything else you leave for the compiler to infer, too.

It is true that editors will be able to show you this information either way, but I think it is still nice to have explicit types so the code its self is readable regardless of tooling.

Well-defined types are lovely

You’ll soon realise how nice well-defined types are to work with. It is most definitely worth the initial pain of forcing yourself to define everything.

I often see objects in JavaScript and wonder, “alright, but what is it?”, when I see it being dotted into. It is such a pleasant developer experience when everything has a definition you can easily read through and understand.

This, combined with good editor support will leave a smile on your face:

As you can see, without is just terrible.

You can contribute third-party types

Most of us have reached a point where we try to import a third-party dependency and it has no types, so we’re either left with a nasty compile error or we were naughty and turned the most lenient compile options on…

We’re all in need of good, strong types for popular dependencies. So if you do find yourself in such a situation, please do write them and contribute them to DefinitelyTyped or the project its self!

It will be of great help to all people who reach the same problems you have in future.

You will learn more advanced types

As you go deeper into the type system and start defining much more complex objects, you’ll learn a lot of fun things.

Things you once thought were too dynamic or difficult to strongly type will end up being easy for you.

A few good examples of what we can do are:

• Conditional types
• Type guard functions
• Mapped types

Wrap up

So to wrap up:

{
  "compilerOptions": {
    "strict": true,
    "noUnusedParameters": true,
    "noUnusedLocals": true,
    "noImplicitReturns": true
  }
}

Then, if you’re ready for it, enable ESLint with the no-explicit-any rule at error level.

Do this, take the hit and you will thank yourself later :)

Deno? What’s that?

I found myself a little unproductive recently, so took a quick look at GitHub’s trending repos page to see if there’s anything cool and new to have a read of.

One of the top results was Deno. This was interesting for a few reasons:

• Written in Rust (this of course meant I had to tell my good friend & “rustacean” @willspeak who loved the logo choice more than anything)
• Natively supports both JavaScript and TypeScript
• Implements ES modules just like a browser

All of these points are of course excellent…

Why would I need it?

It is easiest to think of deno as an alternative to NodeJS. It aims to solve the same problem ultimately.

Node currently struggles a lot with playing nicely with newer APIs and especially ES modules, though. This is where deno comes in, as it aims to implement things the same as browsers do.

You and I would likely choose to use it if we wanted a single code base that can be used in browsers and server-side as-is.

Trying it out

Deno is just another run-time for a language we already know, so your code will pretty much be the same as it would in a browser (ignoring standard library differences for now).

Here’s one of the examples from their docs:

import { listen, copy } from "deno";

(async () => {
  const addr = "0.0.0.0:8080";
  const listener = listen("tcp", addr);
  console.log("listening on", addr);
  while (true) {
    const conn = await listener.accept();
    copy(conn, conn);
  }
})();

Then to run it:

$ deno foo.ts
deno requests network access to "listen". Grant? [yN] y
listening on 0.0.0.0:8080

You can also see here the security part of Deno (which I won’t be going into), in that it has plenty of control over permissions of a script.

Thoughts

A word of warning, most of these are going to be fairly technical points which most people wouldn’t be so concerned about but do affect all of us.

I’ll be explaining these points with the assumption that you’ve gone ahead and tried deno out yourself.

Basics

If we’re not so concerned about the technical differences and differing implementations of internals, both Node and deno behave very similarly.

Though, once it has matured, I think deno will be a good contender for us to all move to.

Imagine writing all your projects, both libraries and apps, in one way and having it work in both browsers and on the server just as-is. It would be an amazing developer experience, and that is where deno is already at.

Modules

One of the big problems with Node right now is that they’re in a difficult position of trying to remain compatible with their own module system (require) and the one defined in the spec (import).

Deno is great here, it doesn’t care about Node’s old off-spec module system and only implements what is in the spec, ES Modules:

// Deno & Browsers
import {Foo, Bar} from './my-module.js';

// Node (CommonJS)
const {Foo, Bar} = require('./my-module.js');

Modules are the greatest part of deno, for me, as it means we can have sources which work in both browsers and deno without the need for changes or a build process.

Package locks, manifests, etc.

A thing I think is kinda missing from deno is the concept of a manifest and possibly also a lock file.

Deno recommends checking your dependencies into source control so the run-time can associate the imports with those files instead of trying to retrieve them each time.

This does get around the need for a lock file, I suppose, but it feels a little unconventional committing my dependencies to git…

Also, it seems like we’re dependending entirely on the dependency URLs not changing in order to keep the same dependency graph between builds. But what if a someone changes a git tag, or a branch, or the URL simply vanishes? An uncached build would have plenty of trouble or a dependency could unknowingly be changed.

As for a manifest, deno recommends creating a package.ts or some such file:

// package.ts
export {Foo, Bar} from 'https://foo.bar/branch/some-package.ts';

// mod.ts
import {Foo, Bar} from './package.ts';

The standard library…

Here’s where deno really becomes an obvious early-stages project which needs a lot of TLC before it can be anything more than an experiment.

Just a few issues I have with it:

• No clear process around what is included (who decides what modules are introduced, or what they provide?)
• Some modules seem rushed (the datetime module is a good example, parsing via a bunch of conditionals)
• Tests are lacking in some modules
• Not all modules follow the same structure, conventions, etc.

I think this drills down to it being written by a very small group of people without any well defined process in place. Hopefully, that will change in future.

Compared with browsers

Being that deno tries to simply implement the same specs that browsers do, it should mean all code is portable (after TypeScript transpilation at least).

This seems to be true, but there are still some minor issues around it.

For example, deno requires extensions on all imports but the TypeScript language service (which editors like VSCode use) doesn’t currently like this and complains.

A few other issues exist around this area from what I remember, but all will be cleaned up/solved in time I am sure.

Wrap up

So to wrap up, I think deno is great and a major step forward. What Node doesn’t dare do (a major breaking change for them), deno can and has done.

This is leading us to a much cleaner, much simpler solution which is aligned perfectly with browsers. This is the way things should be.

I do hope it gets plenty of care, cleanup and so on. Eventually, I’d like to see it at a point where we can all use it without any issues and start enjoying having a single code base for all platforms.

Oh and of course, the logo is excellent.

Lately, I’ve seen some confusion from the Polymer community and consumers of the new LitElement…

The confusion? What are property types? How do we use properties? How do things serialize and deserialize? How does this compare to Polymer?

This post only applies if you pass values by attributes or reflect your properties!

Well here we are…

Polymer

I’m going to assume if you’re reading this, you’re aware of how Polymer works and how to use the basics of it.

We define a property like so:

class MyElement extends PolymerElement {
  static get properties() {
    return {
      prop1: String,
      prop2: Boolean,
      prop3: Object,
      prop4: Array,
      prop5: { type: Array, notify: true }
    };
  }
}

Polymer does some wizardry around this so pretty much all primitives and built in types are parsed correctly.

<my-element prop4="[1,2,3]"></my-element>

The above will result in prop4 being the array, [1, 2, 3] after Polymer deserializes it.

Even Date is parsed correctly and Object is parsed as JSON.

LitElement

Pretty much everyone who came from Polymer makes the mistake of trying the same property types in Lit as they used in Polymer.

In Lit though, I suppose the idea is to remain lightweight, trimmed down and lacking of any fancy logic like what Polymer had. This means most of these types are not supported out of the box.

We define a property the same (which is why this assumption is an easy one to make):

class MyElement extends LitElement {
  static get properties() {
    return {
      prop1: { type: String },
      prop2: { type: Boolean },
      prop3: { type: Object },
      prop4: { type: Array }
    };
  }
}

This won’t work!

Let’s take a look:

• <my-element prop1="foo"> gives us node.prop1 === "foo"
• <my-element prop2="true"> gives us node.prop2 === true
• <my-element prop2="false"> gives us node.prop2 === true
• <my-element prop3='{ "foo": 5 }'> gives us node.prop3 === '{ "foo" : 5 }'
• <my-element prop4="[1,2,3]"> gives us node.prop4 === "[1,2,3]"

You can see the last 3 are confusingly wrong. This is likely not what you expected at all.

How it works

A property type in Lit is a serializer object or function.

When we node.setAttribute('prop1', 'foo') or <my-el prop1="foo">, we actually end up invoking node.prop1 = String('foo').

Whatever we set our type to is used to deserialize the attribute value.

With type: Foo, we would result in node.prop1 = Foo('foo').

It can be one of two possible types…

A Function

const deserializer = (str) => JSON.parse(str);

In this case, given the element above but with:

{
  prop3: { type: deserializer, reflect: true },
  prop4: { type: deserializer, reflect: true }
}

We would end up with:

<my-element prop3='{ "foo": 5 }'></my-element>
<!--
  node.prop3 would be the object { "foo" : 5 }
-->

<my-element prop4="[1,2,3]"></my-element>
<!--
  node.prop4 would be the array [1, 2, 3]
-->

<!--
  Setting node.prop4 = [4, 5, 6] will reflect:
-->
<my-element prop4="4,5,6"></my-element>

A function works when we only want special parsing but are happy with toString when reflecting to the attribute.

You can see from the last example, we end up serializing into 4,5,6 because that is what [4,5,6].toString() results in.

An Object

For cases where we want to handle serialization for reflecting values to attributes, such as in the case of arrays, we need to provide an object:

const deserializer = {
  toAttribute(val) {
    return JSON.stringify(val);
  }
  fromAttribute(str) {
    return JSON.parse(str);
  }
};

Now we see:

<my-element prop4="[1,2,3]"></my-element>
<!--
  node.prop4 would be the array [1, 2, 3]
-->

<!--
  Setting node.prop4 = [4, 5, 6] will reflect:
-->
<my-element prop4="[4,5,6]"></my-element>

The value is serialized correctly!

Built-ins

Boolean, Number and String do work out of the box, kind of.

Now that you know how it works:

Boolean('true') === true
Boolean('false') === true
Number('5') === 5
String('foo') === 'foo'

You see, these constructors happen to behave the same way we want a deserializer function to behave (though Boolean is slightly different).

Boolean is different because Lit handles null as false, for you.

Conclusion

It is a bit confusing, yes.

It definitely means your Polymer properties are not compatible with Lit, as you likely use Object and such a lot.

Lit may end up implementing these common serializers, though, seeing as pretty much everyone would expect to use them. We shall see, as it would also introduce more weight into Lit and that is what the team wants to avoid.

Until then, keep an eye on a little repo I’m playing around with as it aims to provide these common serializers until there’s a better solution (or forever if there never is one).

Enjoy!

As a regular contributor to many Polymer projects, I find myself playing around with Lit quite a lot. Things appear to be fine, everything nicely structured and everything works just as the team has defined…

However, in reality, a lot of people who discover Polymer and Lit will be coming from backgrounds where they have used something completely different or at least something with a very different development workflow.

One of those common workflows is the combination of Rollup, Babel and Karma.

So let’s take a look at how we can apply those while using LitElement…

Project Structure

To begin with, I threw up a pretty basic project structure:

- src/
  - my-element.js
  - index.js
- package.json
- package-lock.json
- .editorconfig

The idea is that we will use Babel to transpile our sources into a lib/ directory and use Rollup to bundle those into a bundle.js.

Our Element

Our obvious dependencies are needed as a start:

$ npm i -S @polymer/lit-element

The element being used for this setup is as follows:

// src/my-element.js
import {LitElement, html, property} from '@polymer/lit-element';

export class MyElement extends LitElement {
  @property({type: String})
  foo = 'test';

  render() {
    return html`<h1>${this.foo}</h1>`;
  }
}

customElements.define('my-element', MyElement);

// src/index.js
export {MyElement} from './my-element';

As you can see, it is fairly straight forward. More information on the lifecycle methods and property setup can be found here and here.

We’re just defining a very simple element which renders its only property, foo.

Babel

First of all, we need to install Babel along with any plugins and presets:

$ npm i -D @babel/core @babel/cli @babel/preset-env
$ npm i -D @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators

The first three are pretty much to allow us to transpile from ES2015 and beyond to a given level (in our case, to ES modules).

The two plugins are needed to allow us the use of Lit’s decorators as you saw above:

export class MyElement extends LitElement {
  @property({type: String})
  foo = 'test';
  /* ... */
}

After installing these, a very simple babelrc will do:

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "modules": false,
        "targets": {
          "esmodules": true
        }
      }
    ]
  ],
  "plugins": [
    [
      "@babel/plugin-proposal-decorators",
      { "legacy": true }
    ],
    [
      "@babel/plugin-proposal-class-properties",
      { "loose": true }
    ]
  ]
}

To try explain this a little, we:

• Enable @babel/preset-env to turn on common Babel features
• Disable module generation ("modules": false) to prevent Babel outputting CommonJS modules but rather have it output ES Modules
• Enable the ES modules target so only browsers which support it are targeted
• Enable legacy decorators (until LitElement supports the newer decorator proposal)
• Enable loose class properties (until we can stop using legacy decorators)

This combination of things will result in us being able to use the provided decorators and have our element properties defined as class properties.

If we didn’t have any of this, our class would instead use the static properties getter:

export class MyElement extends LitElement {
  static get properties() {
    return {
      foo: { type: String }
    };
  }
}

Now if we:

$ node_modules/.bin/babel src -d lib
Successfully compiled 2 files with Babel.

We will have a populated lib/ directory containing our transpiled sources.

We should add this as a script in package.json to make things easier:

"scripts": {
  "build": "babel src -d lib",
}

So we can:

$ npm run build
Successfully compiled 2 files with Babel.

ESLint (optional)

It is fairly easy from this point to add ESLint to the workflow, though not required at all:

$ npm i -D eslint babel-eslint eslint-plugin-lit

babel-eslint is an ESLint parser so we can have ESLint directly understand our pre-transpiled sources. eslint-plugin-lit introduces some handy lint rules specific to Lit.

I used a config like so:

{
  "extends": "eslint:recommended",
  "parser": "babel-eslint",
  "rules": {
    "lit/no-legacy-template-syntax": "warn"
  },
  "plugins": ["lit"]
}

You can add whichever rules you want from the Lit plugin, or none at all if you wish.

Then you can simply introduce a new NPM script:

"scripts": {
  "build": "babel src -d lib",

  "lint": "eslint \"src/**/*.js\""
}

To run:

$ npm run lint

Simple!

Rollup

So far, we do have some sources a browser can understand. However, we do not have support for Node (CommonJS) modules or the Node resolution algorithm.

This is where Rollup comes in:

// without Rollup or a loader/polyfill
import {LitElement} from './node_modules/@polymer/lit-element/lit-element.js';

// with Rollup
import {LitElement} from '@polymer/lit-element';
import someModule from 'a-node-module';

If we use Rollup, we can use all our Node modules as normal and simply have them bundled at build time.

Installing is pretty simple:

$ npm i -D rollup rollup-plugin-commonjs rollup-plugin-node-resolve

The two plugins here give Rollup a helping hand with resolving Node dependencies and understanding CommonJS modules (as opposed to the more modern ES modules).

We can then throw up a config file as simple as:

import resolve from 'rollup-plugin-node-resolve';
import common from 'rollup-plugin-commonjs';

export default {
  input: 'lib/index.js',
  output: {
    file: 'bundle.js',
    format: 'esm'
  },
  plugins: [
    common(),
    resolve()
  ]
};

This is as simple as it looks, it will use the two plugins mentioned earlier and bundle our lib/index.js along with its dependencies into a bundle.js.

We can now introduce yet another NPM script:

"scripts": {
  "build": "babel src -d lib",
  "lint": "eslint \"src/**/*.js\"",

  "bundle": "npm run build && rollup -c"
}

You can see how we chained the Babel build so when we call:

$ npm run bundle

We will actually transpile the sources, then bundle the output.

Now if we were to load our bundle in a browser:

<script type="module" src="bundle.js"></script>

We would make <my-element> available just as expected.

Karma

The last piece of the puzzle, which nobody should ever forget about, is testing!

You may be wondering why we don’t use something like Jest here. The answer to that is very simple: Jest does not (yet?) support browser testing; instead it uses JSDOM which does not yet support the web components APIs.

So, for now (or if you prefer Karma), we can use Karma instead:

$ npm i -D karma karma-chrome-launcher karma-mocha chai

This is a pretty common bunch of dependencies: Karma with Mocha support and Chai assertions.

We can also install Puppeteer to automatically download an appropriate Chrome binary for us:

$ npm i -D puppeteer

Our karma.conf.js is simple too:

// Trick to use the auto-downloaded puppeteer chrome binary
process.env.CHROME_BIN = require('puppeteer').executablePath();

module.exports = function(config) {
  config.set({
    basePath: '',
    frameworks: ['mocha'],
    files: [
      'bundle.test.js'
    ],
    reporters: ['progress'],
    autoWatch: true,
    browsers: ['ChromeHeadless'],
    singleRun: false
  });
}

We are going to create a second bundle specifically for tests (bundle.test.js) and want to use headless Chrome.

To create this second bundle, firstly we need another rollup plugin:

$ npm i -D rollup-plugin-multi-entry

The reason for this is that Rollup doesn’t provide multiple entry point support by default, rather it expects a single entry point and a single output (src/index.js -> lib/index.js).

With this plugin, we can now create a rollup.test.config.js:

import resolve from 'rollup-plugin-node-resolve';
import common from 'rollup-plugin-commonjs';
import multiEntry from 'rollup-plugin-multi-entry';

export default {
  input: 'lib/test/**/*.js',
  output: {
    file: 'bundle.test.js',
    format: 'esm'
  },
  plugins: [
    common({
      namedExports: {
        'chai': ['expect']
      }
    }),
    resolve(),
    multiEntry()
  ]
};

This is all fairly simple… we now use a glob input (lib/test/**/*.js) and have added multiEntry() as a plugin.

We have also specified namedExports because the Rollup plugin has trouble automatically detecting what chai exports, unfortunately.

Another two NPM scripts are then added:

"scripts": {
  "build": "babel src -d lib",
  "lint": "eslint \"src/**/*.js\"",
  "bundle": "npm run build && rollup -c",

  "bundle:test": "npm run build && rollup -c rollup.test.config.js",
  "test": "npm run bundle:test && karma start --singleRun"
}

The first (bundle:test) simply runs our existing Babel build and calls Rollup with our rollup.test.config.js.

The second (test) will run bundle:test and start the karma launcher to execute our test suite.

Example Test

An example test would be src/test/my-element.js:

import {expect} from 'chai';
// Very important to ensure any elements we test are loaded
import '../my-element';

describe('my-element', () => {
  let node;

  beforeEach(async () => {
    // Use createElement to test it is registered correctly
    node = document.createElement('my-element');

    // Connect to DOM in case there's any `connectedCallback` logic
    document.body.appendChild(node);

    // Wait for initial render
    await node.updateComplete;
  });

  afterEach(() => {
    // Remove from DOM, cleanup
    node.remove();
  });

  it('should render', () => {
    const span = node.shadowRoot.querySelector('h1');
    expect(span.innerText).to.equal('test');
  });
});

As you can see, this too is pretty straight forward. We didn’t need any helpers, any fancy testing frameworks or custom loaders. We simply bundle our sources as normal and execute the full test suite in Chrome.

Conclusion

This is a very brief overview of how to set up this common work flow, so I expect there’s plenty missing. I do hope it has helped somewhat, though.

While most of the Polymer team and its community are happy to push the idea of everything being native and working as-is in the browser, it is not always reality.

Maybe you’re required to use this workflow to remain consistent with your other projects, or maybe you just like being able to use Node modules. Either way, this should at least give you an idea of how to stick to that process while also adopting something as new as Lit.

Now whether you use bundlers or not, you can try Lit out. Have a play around!