How to use Web Components with Next.js and TypeScript

In my livestream today I had the need to bring in a spinner component to show work in progress in my app. However found that existing React spinners were too heavy. That’s when I had the idea to use web components in my Next.js (React/Preact) app for the first time ever!

We’ll use as a case study.

Web Components 101

Normally to use a webcomponent in a project you just import it like a library:

  import 'wc-spinners/dist/atom-spinner.js';

and then use it in our JSX/HTML:

    <atom-spinner/> Loading

The web component will encapsulate behavior and styles without the weight of a framework, which is very nice for us.

However when it comes to Next.js and TypeScript, we run into some problems.

TypeScript and Web Components

When you use TypeScript with JSX, it tries to check every element you use to guard against typos. This is a problem when you’ve just registered a component that of course doesn’t exist in the normal DOM:

Property 'atom-spinner' does not exist on type 'JSX.IntrinsicElements'.ts(2339)

The solution I got from this guy is to use declaration merging to extend TypeScript:

// declarations.d.ts - place it anywhere, this is an ambient module
declare namespace JSX {
  interface IntrinsicElements {
    "atom-spinner": any;

Next.js and Web Components

The next issue you run into is server side rendering.

ReferenceError: HTMLElement is not defined

WC’s famously don’t have a great SSR story. If you need to SSR WC’s, it seems the common recommendation is to use a framework like Stencil.js. I have no experience with that.

Since in my usecase I only needed the WC clientside, I found that I could simply defer loading the WC:

function Component() {
  React.useEffect(() => import("wc-spinners/dist/atom-spinner.js")
  , [])
  return (<div>
        // etc
        <atom-spinner />

And that’s that! Enjoy using the platform!

Tagged in: #tech #react #typescript #next.js #web components

Leave a reaction if you liked this post! 🧡
Loading comments...

Subscribe to the newsletter

Join >10,000 subscribers getting occasional updates on new posts and projects!

I also write an AI newsletter and a DevRel/DevTools newsletter.

Latest Posts

Search and see all content