Splitting Web Components into .ts, .html, and .scss files

A custom element (Web Component) can be written in JavaScript like this:

my-component.js

  const template = document.createElement('template');
template.innerHTML = `
  <style>
    .class-one {
      font-size: 2rem;
      color: tomato;
    }
    .class-one .class-two {
      font-size: 4rem;
      color: cornflowerblue;
    }
  </style>
  <div class="class-one">
    Hello <span class="class-two">World</span>
  </div>
`;

class MyComponent extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('my-component', MyComponent);

There are a couple of drawbacks to that:

For full type checking we would prefer TypeScript.
Writing complex CSS without a preprocessor like SASS that enables mixins and nesting is a sub-par experience.
Having to write HTML and CSS inline in a string can not only limit your IDEs ability to autocomplete but it also interferes with tools like stylelint that would scan for .(s)css files.

At the end we want to achieve the following:

Use TypeScript instead of JavaScript.
Use SASS in the SCSS syntax instead of CSS.
Move the template and the styling into their own files.

TLDR: Here is the final setup: https://github.com/LeonEck/wc-split-demo

We begin by splitting our code into three files:

my-component.html

  <div class="class-one">
  Hello <span class="class-two">World</span>
</div>

my-component.scss

  .class-one {
  font-size: 2rem;
  color: tomato;

  .class-two {
    font-size: 4rem;
    color: cornflowerblue;
  }
}

my-component.ts

  import html from './my-component.html';
import css from './my-component.scss';

const template = document.createElement('template');
template.innerHTML = `<style>${css}</style>${html}`;

class MyComponent extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('my-component', MyComponent);

The .html and .scss files were probably what you expected. The HTML stays the same. In SCSS we can take advantage of nesting.

The TypeScript file has gained two imports that will store the content of the referenced files in the variables html and css respectively. Those are then used in the template string where we previously had to write our template and styling.

The extraction of HTML and CSS as well as as the transformation from SCSS to CSS and TypeScript to JavaScript will all be handled by esbuild and the esbuild-sass-plugin.

To get our build setup going we create a package.json with the following content:

  {
  "name": "wc-split-demo",
  "version": "0.0.0",
  "scripts": {
    "build": "node build.mjs"
  },
  "dependencies": {
    "esbuild": "0.20.0",
    "esbuild-sass-plugin": "3.0.0"
  }
}

Run npm install. The build script in our newly created package.json will run node on a file called build.mjs. This is where the magic happens. Create the file and fill it with the following content. Everything is explained inline.

  import { build } from 'esbuild';
import { sassPlugin } from 'esbuild-sass-plugin';

await build({
  /**
   * Point esbuild to the TypeScript file it should build
   */
  entryPoints: ['my-component.ts'],
  /**
   * Activate bundling so that import statements are evaluated
   * and their content inlined
   */
  bundle: true,
  /**
   * .html files should be loaded as text (string) in import statements
   */
  loader: {
    '.html': 'text',
  },
  /**
   * Use esbuild-sass-plugin to compile the SCSS syntax to CSS
   */
  plugins: [
    sassPlugin({
      /**
       * Pass on the generated CSS as a string in import statements
       */
      type: 'css-text',
    }),
  ],
  /**
   * Output format should be an ECMAScript Module
   */
  format: 'esm',
  /**
   * Output from the build
   */
  outfile: 'my-component.js',
});

You can now run npm run build which will produce a my-component.js file with a very similar content to the initial version:

  // my-component.html
var my_component_default =
  '<div class="class-one">\n  Hello <span class="class-two">World</span>\n</div>\n';

// my-component.scss
var my_component_default2 = `
.class-one {
  font-size: 2rem;
  color: tomato;
}
.class-one .class-two {
  font-size: 4rem;
  color: cornflowerblue;
}`;

// my-component.ts
var template = document.createElement('template');
template.innerHTML = `<style>${my_component_default2}</style>${my_component_default}`;
var MyComponent = class extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
};
customElements.define('my-component', MyComponent);

You can find the full source code from this tutorial here: https://github.com/LeonEck/wc-split-demo

And if you are interested in a much more advanced setup you can dig through my eck-autocomplete project.