DEV Community: Benny Powers 🇮🇱🇨🇦

Introducing Backlit: Lit SSR for Drupal, Hold the Node

Benny Powers 🇮🇱🇨🇦 — Thu, 19 Mar 2026 13:38:06 +0000

Two years ago I wrote about server rendering Lit web components with Drupal. The approach worked, but it required a Node.js HTTP service running alongside Drupal in a container. That meant Docker/Podman, networking between containers, and an extra process to manage. It was a proof of concept, and it felt like one.

Well, introducing Backlit -- a Drupal module that server-renders Lit web components with Declarative Shadow DOM. No Node.js, no containers, no external services. Two lines to install, zero infrastructure to maintain.

What Backlit does

If your Drupal site uses Lit web components (from a design system, a custom theme, or anywhere else), those components normally render client-side: the browser downloads JavaScript, defines the custom elements, and paints the shadow DOM. Until that happens, users see a flash of unstyled content or an empty box.

Backlit moves that rendering to the server. When Drupal finishes building a page, Backlit pipes the HTML through a binary that injects each component's shadow DOM directly into the response as a <template shadowrootmode="open"> element. The browser attaches the shadow root during HTML parsing -- before any JavaScript runs. Users see styled, laid-out content on first paint.

Disable JavaScript entirely. The components still render. That is the way of the Lit.

Quick start

composer require bennypowers/backlit
drush en backlit

Composer downloads the right binary for your platform (linux, macOS, Windows; x64 and arm64). Drush enables the module. Done.

What's different from the Node.js approach

The previous post drew three fair criticisms. Here's how Backlit addresses each.

No more service to maintain. The Node.js sidecar is gone. Backlit's binary is a static executable -- it starts on demand inside the PHP-FPM worker and dies with it. Nothing to monitor, restart, or deploy separately. composer update handles everything.

Minimal overhead. The Node.js approach added ~50ms and ~100MB per request. Backlit adds ~0.32ms per render after a one-time 350ms cold start per worker, with a much smaller memory footprint (the binary is ~9MB, the WASM instance lightweight). With Drupal's page cache enabled, subsequent requests skip the binary entirely.

Safe failure and author control. If the binary is unavailable or returns an empty response, Backlit returns the original HTML unchanged -- SSR failure is invisible to end users. Beyond that, Backlit adds an "Enable SSR" checkbox to content types, so authors can disable SSR per-page. Not every layout needs shadow roots injected, and editorial teams should have the final say.

Adding your components

Backlit doesn't ship with any component definitions. You provide them as plain JavaScript files -- the same LitElement classes you'd write for the browser, minus the import statements.

Where to put them

Drop .js files in any of these locations (checked in order):

$settings['backlit']['components_dir'] in settings.php -- explicit path
Your active theme's components/ directory -- e.g., themes/custom/my_theme/components/
Any custom module's js/ directory -- e.g., modules/custom/my_ds/js/

Backlit auto-discovers element names from customElements.define() calls. No further configuration needed.

One caveat

The JS files can't use import statements that reference 'lit' or other npm packages -- the WASM engine has no filesystem or module resolver. Instead, Backlit provides LitElement, html, css, classMap, styleMap, repeat, and unsafeHTML as globals. If your design system distributes pre-built single-file component definitions, they'll work as-is. If not, a quick esbuild --bundle strips the imports and produces a self-contained file.

The component source is sent with each render request, but the WASM engine only evaluates it on the first render -- after that, customElements.get() confirms the elements are already registered and skips the eval. Definitions stay warm across all subsequent renders. No build step, no npm, no bundler at deploy time.

Administering Backlit

Updating components

When your front-end team ships a new version of the design system:

Replace the JS files in your components directory with the updated versions
Clear Drupal's cache: drush cr

The next request restarts the binary with the new definitions. That's the entire update process. No npm install, no container rebuild, no deployment pipeline for a sidecar service.

Updating the binary

When a new version of Backlit is released with engine improvements:

composer update bennypowers/backlit
drush cr

Composer downloads the updated binary. The cache rebuild ensures the old process is replaced.

Monitoring

Backlit logs errors to Drupal's watchdog. If the binary fails to start (missing file, wrong permissions, unsupported platform), you'll see it in the Drupal logs. The page still renders -- just without DSD.

Caching

Backlit runs on every uncached page response. If you have Drupal's Internal Page Cache or a reverse proxy (Varnish, Cloudflare) in front of your site, the rendered HTML (with DSD) is cached at that layer. Subsequent requests never hit the binary. This is the recommended production setup.

Per-content control

Backlit adds an "Enable SSR" checkbox to all content types. It defaults to on. Authors can disable it for individual pages where SSR causes issues -- for example, if a component relies on client-side state that SSR can't replicate.

When to use Backlit

Backlit is useful when:

Your site uses a Lit-based design system (like RHDS, Shoelace, Lion, or your own)
You care about first-paint performance (LCP, CLS)
You want web components to render without JavaScript (accessibility, SEO, slow connections)
You don't want to run Node.js alongside Drupal

How it works under the hood

The binary embeds a WASM module containing QuickJS (a lightweight JavaScript engine) running @lit-labs/ssr. On startup, it reads your component JS files and evaluates them in QuickJS, registering custom elements. Then it enters a read loop: Drupal writes HTML to the binary's stdin (NUL-terminated), the binary renders every known custom element with Declarative Shadow DOM, and writes the result to stdout (also NUL-terminated).

Drupal (PHP) --stdin: HTML\0--> lit-ssr-runtime binary --> stdout: HTML-with-DSD\0

The WASM instance stays warm across renders. The ~350ms cold start is paid once per PHP-FPM worker. Every subsequent render: ~0.32ms.

The binary is built with Go and wazero (a pure-Go WASM runtime -- no CGo, no system dependencies). It's statically linked and runs on any Linux, macOS, or Windows machine. Yes, we support Windows. No, we haven't tested it. Godspeed.

Performance

Metric	Node.js sidecar (2024)	Backlit (2026)
Cold start	~500ms (Node.js boot + module load)	~350ms (WASM compile, once per worker)
Per-render	~50ms (HTTP roundtrip + render)	~0.32ms (pipe I/O + render)
Dependencies	Node.js, npm, Docker/Podman	Single binary
Memory	~100MB (Node.js heap)	~9MB binary (not yet benchmarked at runtime)

These numbers are from the builtin mode (compiled-in components) Go benchmark. Runtime mode -- which Backlit uses by default -- adds overhead for JSON serialization and source transmission, though it skips JS evaluation after the first render. Runtime mode benchmarks are on the to-do list.

Limitations

This is a v0 release. Some honest caveats:

Lit only. The SSR engine is @lit-labs/ssr, which understands Lit's template system. Vanilla custom elements, Stencil, FAST, or other frameworks won't render. If you're using a mixed component library, only the Lit-based elements get DSD.
@lit-labs/ssr is experimental. The Lit team marks it as such. It doesn't support @lit/context, and some component patterns (anything that calls DOM APIs during server render) will fail. Components need to be SSR-compatible.
Component JS must not import from 'lit'. The WASM engine provides Lit APIs (LitElement, html, css, etc.) as globals. Components that use these globals directly work fine. Components with import { LitElement } from 'lit' will fail because QuickJS has no module resolver for npm packages. If your design system distributes components as ES modules, strip the imports first (e.g., esbuild --bundle or a simple regex).
Source sent on every request. The runtime CLI currently sends the full component JS source with each render payload. The WASM side skips re-evaluation, but the serialization overhead is still there. Easy fix for the next release: send source only on the first request.
No streaming. The entire page HTML is buffered, piped through the binary, and buffered back. For very large pages this adds latency. Streaming SSR is technically possible but not implemented.
Single process. One lit-ssr-runtime process per PHP-FPM worker. Under high concurrency, this could be a bottleneck. A pool-per-worker model is straightforward to add.

Advanced: compiled mode

For sites where every millisecond counts, you can build a custom WASM module with your components baked in, skipping JS evaluation entirely:

Clone lit-ssr-wasm
Write your components in src/components/ (standard TypeScript with decorators)
Import them in src/entry.ts, add tag names to KNOWN_ELEMENTS
npm run build (requires Javy)
Build the CLI: cd go && make linux-x64
Replace the binary in Backlit's bin/ directory

This is the "I have a build pipeline and I'm not afraid to use it" option. Most sites won't need it.

Try the demo

The drupal-lit-ssr-wasm repo has a fully working example with auto-install, demo content, and Docker Compose:

git clone https://github.com/bennypowers/drupal-lit-ssr-wasm
cd drupal-lit-ssr-wasm
./scripts/download-binary.sh v0.0.2
podman compose up

The first boot takes a few minutes (Drupal auto-installs via Drush). Browse to http://localhost:8888. The front page shows server-rendered web components. Disable JavaScript to verify.

Live demo

The lit-ssr-wasm demo runs the actual WASM modules directly in the browser using a minimal WASI shim. The compiled mode demo does not load any JavaScript definition of <my-alert> on the page -- the styles you see come entirely from Declarative Shadow DOM.

Alternatives

Backlit ships the CLI binary approach because it's the easiest to deploy. But I've considered a few other directions, and I'd be happy to explore any of them further if there's interest -- consider this a teaser of what Backlit could become.

Extism PHP SDK -- a WASM plugin framework with a Composer-installable PHP SDK. In-process execution without shelling out. Requires libextism.so on the host, but removes the subprocess entirely.
wasmer-php -- a PECL extension for running WASM directly in PHP. More complex to deploy (requires compiling the extension), but eliminates IPC overhead entirely.
PHP FFI + Go shared library -- build a .so from the Go code using -buildmode=c-shared and call it via PHP's FFI. More complex, less isolation, but potentially the lowest-latency path.

If one of these fits your deployment better than the binary approach, open an issue and let me know -- that's exactly the kind of feedback that shapes what gets built next.

What's next

Backlit is deliberately minimal. Future directions:

Manage multiple lit-ssr processes (one per PHP-FPM worker) for parallel rendering
Add a Drush command for pre-warming the WASM instance on deploy
Drupal admin UI for managing component sources

The Backlit module, the lit-ssr-wasm engine, and a working Drupal demo are all on GitHub.

This is early days. I'd love to hear what breaks, what's missing, and what you'd build with it. Open an issue on the Backlit repo, or on lit-ssr-wasm for the engine itself. PRs welcome. Bug reports welcomed even more warmly.

Thanks to Steven Spriggs for talking through the idea and vetting the approach with me. Steven built his own Go-based Lit SSR pipeline, golit, taking a different path to the same destination -- worth knowing about if Backlit's tradeoffs don't fit your setup.

You know, it's funny; I built lit-ssr-wasm to scratch a completely different itch -- a live preview feature in cem serve. Backlit happened because, once the WASM module existed, the Drupal integration practically wrote itself. Two years of "this should be simpler" collapsed into an afternoon. That's the thing about building on standards. WASM is to backend runtimes what web components are to the browser: write it once, run it anywhere, watch it quietly solve problems you weren't even trying to solve. I'll take it.

GNOME 2.20 but its Web Components

Benny Powers 🇮🇱🇨🇦 — Sun, 01 Mar 2026 13:48:22 +0000

A couple of days ago, this youtube video rolled into my recommendations feed

It's an essay by this youtuber called onion boots on how websites used to be weird and playful. And I got to thinking about how I missed that old timey tinkerer's network. Then I thought at my website, and how it looks like... a website, and decided it wasn't weird enough.

Well, its a few days later and I've turned my website into the GNOME 2 desktop circa 2002. It's built out of web components, using Lit. Specifically I used lit-ssr to generate DSD templates, and the newly baseline View Transitions API to make "focusing" (navigating) between "windows" (pages) feel more fluid and natural.

I'm going for a classic feel here, so I designed the webmentions (which used to appear in a sidebar or under the post) UI to look like a Pidgin IM session, and the slide decks page looks (kinda) like OOO Impress.

It's got two themes. Clearlooks is based on the original CSS, and Clearlooks dark is "inspired" thereby. Maybe I'll add more themes down the line if I'm feeling up to it. I also shipped the default GNOME desktop wallpapers, so pick whichever one you like best.

It's even got Minesweeper, and calculator!

So yeah this is pretty silly but I'm also committed to the bit 🤣. Which app should I implement next? Send me a webmention to this page.

Introducing The Custom Elements Dev Server

Benny Powers 🇮🇱🇨🇦 — Thu, 04 Dec 2025 14:00:00 +0000

If you're building web components, you've probably used Storybook. It's great! But it's also framework-focused, requires writing stories in JavaScript/MDX, and adds a lot of overhead when all you really want is to see your HTML custom elements in a browser.

That's why I built cem serve: an opinionated development server designed specifically for web components and HTML.

What is cem serve?

Think Storybook for HTML. It's a custom-elements manifest-driven development server for your web components. You write short HTML partials which show off your components, and cem serve wraps them up into a live-reloading dev server with auto-generated knobs.

The server's UI and workflow are based on your Custom Elements Manifest. It uses the same code as in the cem generate command to discover HTML demos according to your configuration, then it generates demo pages complete with interactive knobs, based on your manifest metadata. When you edit demo files or their dependencies, the server reloads the page for you.

One of the nicest features is the buildless development workflow: cem serve automatically transforms TypeScript to JavaScript, and CSS module scripts (e.g. import styles from './my-button.css' with { type: 'css' }), on-the-fly.

Usage

Write JSDoc, or HTML and CSS comments to document your components. If you're using Lit and TypeScript, cem generate will pick up on your @property decorators and add them to the manifest as attributes. It also automatically detects slots in your render() method, so you don't need to declare them in JSDoc.

Tell cem about your demo files by adding the generate.demoDiscovery setting, or by using the @demo JSDoc tag.

import { LitElement, html, css } from 'lit';
import { customElement, property } from 'lit/decorators.js';

import styles from './my-button.css' with { type: 'css' };

/**
 * A button for performing actions
 * @demo demo/index.html
 */
@customElement('my-button')
export class MyButton extends LitElement {
  static styles = [styles];

  /** Button variant (primary, secondary, danger) */
  @property() variant = 'primary';

  /** Button text */
  @property() label = '';

  /** Disabled state */
  @property({ type: Boolean, reflect: true }) disabled = false;

  render() {
    return html`
      <button ?disabled=${this.disabled}>
        <!-- Text label, or additional content, like icons -->
        <slot>${this.label}</slot>
      </button>
    `;
  }
}

Optionally, run the cem generate command to create your custom-elements.json file, with all your component metadata - attributes, properties, events, slots, everything.

cem generate

Don't worry about skipping this step, cem serve will create one for you in-memory when you launch the server.

Writing HTML Demos

Demo files are HTML partials which users of your elements can copy and paste on to a page. cem serve will wrap them up in a helpful UI, so don't worry about <html>, <head>, or <body> elements.

Here's an example demo:

<my-button variant="primary"
           label="Click me"></my-button>

<script type="module">
  import '@my-elements/my-button.js';
</script>

The demo includes everything a user would need to drop the element on a page (assuming an import map is set up) You can also include inline style tags or link to stylesheets if you need to. The idea is to demonstrate a complete unit, in terms of simple HTML, CSS, and if necessary, JavaScript.

Running the Dev Server

npx @pwrs/cem serve

Open http://localhost:8000 and you'll see a listing of all the demos in your project.

Auto-Generated Knobs

With cem serve, knobs are auto-generated from your manifest. Document your component once, get knobs for free, without defining them explicitly in code.

Knobs are based on the entries in your manifest, so if your attributes and class fields are well-typed (via JSDoc or TypeScript typings), then the generated knobs will match: text input for strings, number input for numbers, select fields for enums.

Why it Matters

The cem project in general pursues a standards-based development model, where the least amount of magic and framework cruft is applied to the development loop.

The addition of the dev server closes the gap, now cem is a complete development toolkit for web components, combining manifest generation, dev server, lsp for editor support, and mcp for AI support.

Demos are Just HTML

With cem serve's workflow, your demos aren't framework-specific stories, or a custom markdown flavour; they're pure HTML. That means your users can copy them directly from your docs. They also work in any environment (React, Vue, vanilla JS, whatever). Your demos don't require any special knowledge to read and understand, anyone who knows HTML, JS, and the DOM can read your demos. There's no framework version lock-in, and LLM
coding tools can easily convert them from basic DOM to framework integrations, if needed, especially by leveraging cem mcp.

How Does This Compare?

Let's look at cem serve alongside other popular development tools:

Feature	cem serve	Storybook	Vite	@web/dev-server
Purpose	Web component preview	Component stories	General dev server	General dev server
Demo Format	Plain HTML	JSX/MDX stories	HTML/Framework	HTML
Component Isolation	✅ Built-in	✅ Built-in	❌ None	❌ None
Interactive Knobs	✅ Auto-generated	✅ Manual setup	❌ None	❌ None
Demo Discovery	✅ Manifest-driven	✅ Story files	❌ Manual	❌ Manual
TypeScript	✅ On-the-fly	⚠️ Requires build	✅ On-the-fly	⚠️ Plugin needed
Reload Strategy	Full page	HMR/Full page	HMR	Full page
Configuration	Low (manifest)	Medium	Low	Low

When to Use Each

Use @web/dev-server or Vite if you need a generic, fully customizable dev server. Use Storybook if you're locked in to legacy frameworks, are hooked on their extensive addon ecosystem, or just have thing for MDX.

Use cem serve when you're building web components in isolation and want a hassle-free, streamlined development workflow.

The sweet spot for cem serve is component libraries that need to work across frameworks. Your demos are HTML, so they're portable. Your knobs come from the manifest you're already generating. Zero configuration.

Try It

npm install --save-dev @pwrs/cem
npx @pwrs/cem serve

go install bennypowers.dev/cem
cem serve

Works best with LitElement or vanilla custom elements. If you've already got a Custom Elements Manifest, you're golden.

Links

Built with Go, TypeScript, PatternFly Design System, and Web Components. Licensed GPL-3.0-or-later.

Have questions or feedback? open an issue.

Your Design System is Not a Solution

Benny Powers 🇮🇱🇨🇦 — Mon, 23 Sep 2024 15:12:17 +0000

You've got a problem. Your painting fell, and you want to hang it back up.
You grab a hammer and some nails, you get to swinging, you make a few
adjustments, and Hey Presto! before you know it, your problem is solved.

You have implemented a solution: you hung the painting.

Just then, your neighbour knocks on the door. Wouldn't you know it? he also
has a problem. His painting has fallen, too. He also needs a solution. Being
the magnanimous, good-looking, and preturnaturally charming neighbour that you
are, you leap into motion, practically stuffing his arms with hammer and nails,
and you send him on his way, richly satisfied by your own generosity.

An hour later, he knocks again. You see — your house is built of timber and
drywall, while your neighbour's house is built of cinderblocks and plaster. Your
neighbour now has two problems — his painting is still on the floor, and he
now has an unsightly hole in the wall.

Tools, or Solutions

Now, your solution needed a bunch of tools to get 'er done:

the hammer
the nails
maybe a level or a tape measure
your skill at swinging the hammer
barring that, a bag of frozen peas
the impeccable taste of your living companions

Some of those tools were essential to the solution, others less so. But they
all have one thing in common:

none of those tools is the solution to your problem.

If you really needed to, you could probably hang that painting with an old shoe

Consider, too, that your solution didn't work for your neighbour, who built with
cinderblocks and plaster, and actually made things worse for him. What went
wrong? Was it the tools you gave him? Not necessarily. He might have used the
hammer you gave him to drive special cinderblock nails or those plastic-and-tack
plaster hooks.

The problem wasn't the tools — the problem was seeing the tools as the
solution.

Jackhammers require care in use. Thumbtacks are cheap, plentiful, and not
particularly dangerous. Both are needed on a construction site — one to break
large blocks of concrete and rock, one to hang plans and blueprints. Both tools
are important — crucial even — in their own ways, but they have widely different
costs, lifespans, and restrictions on their use.

Cui Bono?

If you've been following along, you're probably waiting for the punchline,
so here it is:

Your design system is not a solution, it's a toolkit

So why do companies adopt design systems? Are they just spinning their wheels?
Well, my desire to continue receiving a steady paycheque requires me to say, "No,
they aren't! Design systems really do solve problems for companies!" But there's
an important difference between the kind of problem which design systems solve
and your team's design problem.

Companies adopt design systems because they want:

a "single source of truth"
consistent visual style across large teams
consistent standards of accessibility
UX/UI recommendations lovingly crafted by specialists

All of these are fancy ways of saying they want to establish and enforce
rules and guidelines for producing user interfaces. Design systems help solve
that problem by centralizing the know-how for building the components of those
interfaces in a way which can be easily ported to different teams'
workflows.

Mowing the Neighbour's Lawn

Design systems can't and shouldn't try to solve every problem for every team.
This industry is by its nature prone to widely varied opinions and approaches,
one often incompatible with the other, and establishing a baseline is hard
enough without shipping bespoke implementations for each team that comes along.
The reasons for this become immediately clear once you shift perspective from
that of the product maintainer to that of the design system maintainer.

The specialist skills needed to produce a design system are not the same as
those needed to ship products. Product teams often need to move quickly to ship
new features, built on top of the previous framework, and they often don't have
the luxury of The Big Rewrite™.

From the design system maintainer's point of view, the customer is actually the
product owner/developer. That's not to excuse design systems from concerning
themselves with end users — quite the opposite. But rather, as toolmakers,
their primary responsibility is to produce quality tools for their fellow
craftsmen.

If you don't own the problem, you can't own the solution

Since different projects have different toolchains, histories, and processes,
they have different constraints as well. What appears to be a non-starter to one
maintainer is a no-brainer to another. Because of this, design system engineers
would do well to focus their effort on platforms rather than
frameworks.

Tech Debt up to Here

So, your design system is now free to build on top of platform primitives, and
there are greenfield projects and high-velocity teams reaping the benefits of
platform-oriented development. Lechaim — 🥃 Fancy bourbon all around! But that
still doesn't solve the problem of legacy framework integration. Who's left
holding the bag?

Some organizations solve this by reimplementing their design system for every
framework that comes along. To my taste, this practice is error-prone; remember
our initial goals from above. Web development is complex enough when targeting
the browser: duplicating that effort across multiple frameworks scales that
complexity geometrically. It also requires more resources, effort, attention,
and time.

Moreover, tracking integration problems inside the design system repositories
can lead to an awkward situation where greenfield users might mistakenly adopt
the workarounds and second-bests in place of the happy path. There are costs to
increasing API surface, and teams responsible for shipping tools to diverse
projects shouldn't be burdened with the maintenance of those workarounds, when
they have other customers who don't need — and shouldn't try — to adopt them.

Design systems that rest on platform features like custom elements, shadow DOM,
import maps, and plain-old CSS can adapt to multiple projects and frameworks.
It remains true that legacy frameworks have varying degrees of capability when
it comes to integrating with platform features newer than 2019, but it's not
impossible by any stretch of the imagination.

Solving Integration Problems

Rather than being tasked with owning, implementing, and delivering solutions to
legacy framework integration problems, design system teams should be empowered
to consult with and advise those teams to solve the problems on their own
terms.

Design system teams can solve integration problems, but they can't own them.
It's crucial for teams to communicate clearly and openly, and to understand the
business needs that design systems solve. When approaching a difficult
integration, everyone at the table needs to understand the boundaries and
junctions between business needs, framework limitations, and design system
priorities. Downstream teams have to be willing to work with design systems
people to integrate solutions which serve the broader business, and design
systems people have to be willing and able to cross the aisle to work with
downstream on their turf.

Clear boundaries and the application of Postel's law are the
fundamentals of fruitful large-scale software collaboration.

Be conservative in what you do, be liberal in what you accept from others.

Many thanks to my design-systems colleagues Steven Spriggs, Brian Ferry, and
Greg Gibson for their helpful notes on earlier drafts of this post.

Typescript Eleventy Config

Benny Powers 🇮🇱🇨🇦 — Tue, 03 Sep 2024 15:02:14 +0000

There are a bunch of guides out there explaining how to write 11ty configs in typescript so that you can compile them prior to running 11ty. This isn't one of those. I'm here to explain how to run eleventy on your typescript configs, with all the familiar editor ergonomics, without building your config files at all. Dev time, meet runtime.

You'll need node.js 22.6 or later, which adds the --experimental-strip-types flag. What this does is tell node to just ignore typescript syntax, as if it was a comment. Node here is basically implementing the types as comments proposal, and I hope everyone else follows suit quickly.

Doing the Cool Kids' Homework

Now, 11ty follows the types-in-jsdoc approach, which is fine i guess whatever, but for some reason, they don't then ship those types in .d.ts files, so we'll have to build them ourselves. Run this script in postinstall:

import { $ } from 'execa';

import Manifest from '../package.json' with { type: 'json' };

await $`npx tsc node_modules/@11ty/eleventy/src/UserConfig.js
        --declaration
        --allowJs
        --emitDeclarationOnly
        --moduleResolution nodenext
        --module nodenext
        --target esnext`;

for (const pkg in Manifest.dependencies) {
  if (pkg.startsWith('@11ty')) {
    const spec = import.meta.resolve(pkg).replace('file://', '');
    try {
      await $`npx tsc ${spec}
              --declaration
              --allowJs
              --emitDeclarationOnly
              --moduleResolution nodenext
              --module nodenext
              --target esnext`;
    } catch(e) {
      console.log(e.stdout);
    }
    console.log(`Wrote types for ${pkg}`)
  }
}

Shipping .d.ts type declarations in your npm library is an accessibility issue. Your users with cognitive disabilities like ADHD can't afford to keep alt-tabbing back to your docs site. I hope the 11ty authors will integrate this into their build system soon.

TypeScript, Ho!

That having been accomplished, rename your config file and import the UserConfig type:

mv eleventy.config.js eleventy.config.ts

import type { UserConfig } from '@11ty/eleventy';

export default function(eleventyConfig: UserConfig) {
  eleventyConfig.
}

And watch those LSP-completion suggestions roll in.

If you have split your config into multiple files, you need to enable .ts extension in your tsconfig.json. Also disable emit, because we're not actually running tsc at any point, this is all for neovim.

Here, crib mine:

{
  "compilerOptions": {
    "module": "NodeNext",
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "moduleResolution": "NodeNext",
    "allowImportingTsExtensions": true,
    "target": "ESNext",
    "noEmit": true
  }
}

Last thing is to actually run it, and to do that we'll use the NODE_OPTIONS environment variable

"scripts": {
  "build": "NODE_OPTIONS='--experimental-strip-types' eleventy --config=eleventy.config.ts --incremental",
  "start": "NODE_OPTIONS='--experimental-strip-types' eleventy --config=eleventy.config.ts --serve --incremental"
},

Gimmie the Code

And that's pretty much it! I accomplished the above on this site in commit 307e5cf8, which you're welcome to ogle over at Microsoft's loss-leader code scraping utility.

Turn a Micro:bit into a Dreidle

Benny Powers 🇮🇱🇨🇦 — Sun, 11 Dec 2022 22:45:38 +0000

Let's use makecode to turn a micro:bit into a dreidle!

Micro:bit is a tiny opensource device designed and sold by the BBC. It's made to teach computing and electical engineering concepts to students of all ages and it's a treat to hack around with.

A dreidle is a four-sided top marked with the Hebrew letters נ, ג, ה, and פ. You use it to trick Seleucid Greek Gestapo into thinking you're gambling when you're really clandestinely learning Torah.

Clearly, these two things were made to be one.

Sevivon, Sov Sov Sov

Let's start a new project and flip to the JavaScript editor (which is actually a typescript editor but who's counting?), since posting code blocks is easier than taking screen shots 😄.

The plan is to use the RNG to simulate a drey (spin) of the dreidle, picking a number from 0-3, then depending on which number we get, we'll display a different letter on the screen.

Let's start by generating a random number whenever we shake the micro:bit, and storing it in a variable called pan, which means "face" in Hebrew, as in the face the dreidle landed facing up.

function drey() {
  const pan = Math.randomRange(0, 3);
}

input.onGesture(Gesture.Shake, drey);

That having been accomplished, let's then display a given glyph. Since we're using the JavaScript editor we're less encumbered, ~~so we can use a number of JavaScript constructs to pick and show our glyph~~ LOL nope, we still have to pass string literals to showLeds, so our JS code will still be very congruent with blocks code. If we were using the blocks editor, we'd need to use the if / then / else block and drag in and duplicate "Show LEDs" blocks, which we'll also more-or-less be doing here, but at least we'll get to use switch

function drey() {
  const pan = Math.randomRange(0, 3);
  switch (pan) {
    case 0:
      return basic.showLeds(` ..#..
                              ...#.
                              ...#.
                              ...#.
                              .###.`);

    case 1:
      return basic.showLeds(` ..#..
                              ...#.
                              ...#.
                              ...#.
                              .##.#`);

    case 2:
      return basic.showLeds(` #####
                              ....#
                              ....#
                              #...#
                              ##..#`);

    case 3:
      return basic.showLeds(` #####
                              .#..#
                              .##.#
                              ....#
                              #####`);
  }
}

Honestly, if someone sent you a PR like that... I'm telling you those Greeks won't know what hit 'em. 🤔 I wonder if we could hack around makecode's requirement to use a template literal by passing a tagged template literal?

Hmm, guess not. 🤷.

Adding Sounds

Fine, the dreidle spins, but where's the pathos? Let's play a crushing dirge when we lose a throw, and the twinkling melody of gold coins when we take the pot:

case 0:
  music.playSoundEffect('sad', SoundExpressionPlayMode.InBackground);

case 1:
  music.playSoundEffect('twinkle', SoundExpressionPlayMode.InBackground);

Now comes the fun part. When we tap the micro:bit's logo, let's play a little ditty to remind ourselves (and any adults who happen to be in earshot) precisely which holiday is approaching, in case it wasn't already clear to them.

I haven't figured out how to define your own melodies using the keyboard inputs, so let's just play the notes one by one:

function sevivon() {
  music.playTone(Note.D, 200);
  music.rest(40);
  music.playTone(Note.D, 200);
  music.rest(40);
  music.playTone(Note.E, 480);

  music.playTone(Note.F, 200);
  music.rest(40);
  music.playTone(Note.F, 200);
  music.rest(40);
  music.playTone(Note.E, 480);

  music.playTone(Note.A, 200);
  music.rest(40);
  music.playTone(Note.A, 200);
  music.rest(40);
  music.playTone(Note.G, 480);

  music.playTone(Note.F, 200);
  music.rest(40);
  music.playTone(Note.F, 200);
  music.rest(40);
  music.playTone(Note.E, 480);
}

input.onLogoEvent(TouchButtonEvent.Pressed, sevivon);

This way, if any of Antiochus' Nazi thugs try to interrupt our holy game of craps, we'll just tap the logo again and again until they're driven away by sheer bloopety bleepety annoyance. Brilliance!

Grab the final code here 👇

function sevivon() {
    music.playTone(Note.D, 200)
    music.rest(40)
    music.playTone(Note.D, 200)
    music.rest(40)
    music.playTone(Note.E, 480)

    music.playTone(Note.F, 200)
    music.rest(40)
    music.playTone(Note.F, 200)
    music.rest(40)
    music.playTone(Note.E, 480)

    music.playTone(Note.A, 200)
    music.rest(40)
    music.playTone(Note.A, 200)
    music.rest(40)
    music.playTone(Note.G, 480)

    music.playTone(Note.F, 200)
    music.rest(40)
    music.playTone(Note.F, 200)
    music.rest(40)
    music.playTone(Note.E, 480)
}

function drey() {
    switch (Math.randomRange(0, 3)) {
        case 0:
            music.playSoundEffect('sad', SoundExpressionPlayMode.InBackground);
            return basic.showLeds(` ..#..
                                    ...#.
                                    ...#.
                                    ...#.
                                    .###.`);

        case 1:
            music.playSoundEffect('twinkle', SoundExpressionPlayMode.InBackground);
            return basic.showLeds(` ..#..
                                    ...#.
                                    ...#.
                                    ...#.
                                    .##.#`);

        case 2:
            return basic.showLeds(` #####
                                    ....#
                                    ....#
                                    #...#
                                    ##..#`);

        case 3:
            return basic.showLeds(` #####
                                    .#..#
                                    .##.#
                                    ....#
                                    #####`);
    }
}

input.onGesture(Gesture.Shake, drey);
input.onLogoEvent(TouchButtonEvent.Pressed, sevivon);

Take it for a spin (🥁) in the simulator:

Or take a look at a blocks version for younger kids.

Happy Hannukah!

Form-Associated Custom Elements

Benny Powers 🇮🇱🇨🇦 — Tue, 15 Nov 2022 09:49:39 +0000

Form-Associated Custom Elements are a new web standard by which to build custom interactive form controls like buttons, inputs, checkboxes, etc. They present a path forward for design-systems and other custom element authors to more deeply integrate with the web platform. In this post, we'll build a simple FACE to get a feel for the APIs.

How Does this Help?

FACE adds crucial accessibility and interactivity features to web components, closing gaps between web components, framework components, and native browser controls. Before FACE, web component authors had to apply one of a number of workarounds each with their own trade-offs.

Teams developing FACEs can now implement accessible custom controls with simpler HTML APIs while retaining the benefits of Shadow DOM.

But before we get to the code, some history:

skip the history bit

How we Got Here

The web components v1 standard originally defined two kinds of custom elements. The most popular kind is called and autonomous custom element, and
it's what most people think about when they think of web components. The other kind is called a customized built-in element, and they look like this:

class XButton extends HTMLButtonElement {
  static is = 'x-button';
}
customElements.define(XButton.is, XButton, {
  extends 'button',
});

You use CBIEs like this:

<button is="x-button">I'm an XButton</button>

Notice the big differences here: XButton the customized built-in extends HTMLButtonElement, not HTMLElement, and when you register it, you have to pass both the custom element name x-button as well as the localName of the button element it extends. When using it in HTML, the localName of the element is button and the is attribute determines which subclass of HTMLButtonElement to upgrade with.

The chief advantage of customized built-ins was that they came with all the original features of their base elements, well, built-in. So a custom-element author wouldn't need to implement a bunch of stuff to make their custom textfield go, rather they could just extend the existing HTMLInputElement class and get all the necessary and expected functionality (especially crucial accessibility features) for free. Typical OOP stuff. So if customized built-ins are so great, how come this post isn't about them and how come we rarely see them?

Unfortunately, although customized built-ins remain a part of the spec, you should not build them. The reason for this is discouraging: despite the spec's ratification, Apple's WebKit team stated that they would decline to implement customized built-ins.

Since WebKit enjoys an artificial monopoly on iOS devices, the WebKit team's decision has an outsized effect on the industry. Think "US Electoral College", but for web browsers. Their decision not to implement makes customized built-ins a non-starter. Some prominent web developers (most notably Andrea Giammarchi) have advocated permanently adopting a polyfill, but the broader web components community has generally acquiesced to WebKit's decision.

Which is how FACE came to be, it's the alternative to CBIEs that the WebKit team championed.

Workarounds

Before FACE, page authors using custom elements had two options to submit forms with data from their web components:

The "decorator pattern" - slotting native controls into autonomous custom elements
Using JavaScript to manually submit form data

Each of these had their pros and cons.

The Decorator Pattern

The most versatile workaround for autonomous custom controls involves slotting native controls into the custom element.

<x-checkbox>
  <input type="checkbox">
</x-checkbox>

The advantages to this approach include <noscript> support and hassle-free form participation. The disadvantages include HTML noise and awkward styling due to the current limitations of ::slotted(). This is compounded by the requirement to <label> elements, leading to stricter HTML requirements, copying nodes into the shadow root, producing hidden light DOM nodes, or other workarounds-for-the-workaround.

Manually Submitting Forms

Developers working on SPAs might opt instead to put their native inputs in the shadow DOM and use JavaScript to submit the form data to a JSON API. Here's a simple example of how that might work:

form.addEventListener('submit', function(event) {
  event.preventDefault();
  const body = JSON.stringify(somehowCollectFormValuesFromCustomControls());
  const { action, method = 'POST' } = form;
  fetch(action, { method, body });
})

Given the right abstractions this approach could be quite productive for developers, but ties the controls to JavaScript.

Creating a FACE

Form-Associated Custom Elements solves one of the problems that is and customized built-in elements would have solved, namely, allowing your web component to participate in native web forms.

We create a FACE by setting the static formAssociated boolean flag and registering the custom element.

class XCheckbox extends HTMLElement {
  static formAssociated = true;
}

customElements.define('x-checkbox', XCheckbox);

A Free Lunch

So what does this give us? Well, right off the bat, that one static class boolean adds a number of form-related behaviours to our otherwise plain element. The name, form, and disabled attributes now work the same as native <input> elements, and the presence of the readonly attribute will prevent the browser from trying to validate your field, although you're still responsible to make the control actually non-editable. Naming your FACE and specifying a form (by child composition or via form attribute) adds it to the form's HTMLFormControlsCollection, as well, if the element or it's containing <formset> has the disabled attribute, it will gain the CSS state :disabled.

<form>
  <fieldset disabled>
    <label for="xcheck">Check?</label>
    <x-checkbox id="xcheck"
                name="checkit"
                value="checkit"></x-checkbox>
  </fieldset>
</form>

In the above snippet, our custom checkbox is disabled on account of its containing fieldset, and the form submits with its value on checkit. Removing disabled from the fieldset also unsets it from the element, without the element author needing to apply any extra code.

We also get some new lifecycle callbacks:

formAssociatedCallback(form: HTMLFormElement) runs when our element is associated with a <form>, either by being it's child or by setting the element's form attribute to the id of the form.
formDisabledCallback(state: boolean) runs when the element's disabled state changes, either because it or it's containing fieldset's disabled attribute changed.
formResetCallback() runs when the element's associated form has it's reset() method called. You can use this e.g. to reset to a default value.
formStateRestoreCallback(reason: 'autocomplete'|'restore') runs when the browser autofills the form. It takes a single argument of type 'autocomplete'|'restore', depending on whether the browser called it because of an autocomplete or a navigation.

All of that comes for free, even before implementing any actual custom control behaviour. So let's add in the actual checkbox stuff now, just like we would have done before the new standards.

Customizing the UI

Let's start by writing an accessor pair to link our element's checked property to the corresponding HTML attribute:

get checked() { return this.hasAttribute('checked'); }
set checked(x) { this.toggleAttribute('checked', x); }

Built-in checkboxes set their value DOM property to either the value attribute's value or the string on, so let's do that too:

get value() { this.getAttribute('value') ?? 'on'; }
set value(v) { this.setAttribute('value', v); }

We'll add checked and value to our observedAttributes list, then call our connectedCallback (providing a highly aesthetic UX), in attributeChangedCallback.

connectedCallback() {
  this.#container.textContent = this.checked ? '✅' : '❌';
}

attributeChangedCallback(name, _, value) {
  switch (name) {
    case 'checked': this.checked = value != null; break;
    case 'value': this.value = value; break;
  }
  this.connectedCallback();
}

And last we'll add some keyboard and pointer interaction

constructor() {
  super();
  this.addEventListener('click', this.#onClick);
  this.addEventListener('keydown', this.#onKeydown);
  this.attachShadow({ mode: 'open' })
    .append(XCheckbox.template.cloneNode(true));
}


#onClick() {
  this.#toggle();
}

#onKeydown(event) {
  switch (event.key) {
    case ' ':
      event.preventDefault();
      this.#toggle();
  }
}

#toggle() {
  this.checked = !this.checked;
}

Now that our checkbox looks and feels like a checkbox, the last thing to do is to hook into the browser's HTML form lifecycle with another new standard, ElementInternals.

Form Interactions

Along with FACE, ElementInternals gives custom element authors new capabilities. Specifically, element internals are a standard place to implement things like form control validation and accessibility. ElementInternals is designed as a catch-all bag of properties and methods for working with custom elements. We can expect expansions to its capabilities in the future, but for now it contains three parts:

A reference to the element's shadow root, if it exists
Form-related properties
Accessibility-related properties

HTMLElement get a new standard method called attachInternals() which returns an ElementInternals object. This method may only be called on autonomous custom elements and will throw if called on built-ins, customized or otherwise. You hook your control's custom implementation into it's associated form with ElementInternals' form properties.

Let's create our ElementInternals object by callingattachInternals, and store it on a private class field.

#internals = this.attachInternals();

Then, in our connectedCallback, we'll apply the checkbox' value to it's
FormData entry:

this.#internals.setFormValue(this.checked ? this.value : null);

That setFormValue call is part of the ElementInternals secret sauce. Calling it with a non-nullish value adds our control's value to the form's FormData object, whereas calling it with null removes the value.

We can also implement form validation in our custom controls with the following internals properties and methods:

willValidate(): boolean checks whether the element will be validated when the form submits
setValidity() sets the element's form validity state
checkValidity() and reportValidity() work just like their native counterparts.

Custom validations are a big topic so let's save their more in-depth explanation for another day.

Accessibility

The other major feature of ElementInternals are it's a11y-related properties role and aria*. Part of the AOM, we can now set ARIA properties imperatively without needing to set aria- attributes. These are critical capabilities which previously only had partial workarounds.

Let's start by setting the role so that screen readers announce our element as a checkbutton. Note that as of this writing Firefox (107) has not yet implemented role reflection, so we'll do some feature detection

if ('role' in ElementInternals.prototype)
  this.#internals.role = 'checkbox';
else
  this.setAttribute('role', 'checkbox');

We'll update our connectedCallback to render to the a11y tree as well as the DOM. Like role reflection, we'll apply a workaround for Firefox:

if ('ariaChecked' in ElementInternals.prototype)
  this.#internals.ariaChecked = String(this.checked);
else
  this.setAttribute('aria-checked', String(this.checked));

Putting it all together, our custom checkbox:

implements it's own bespoke UI
participates in HTML forms like a native input
is accessible to users of assistive technologies

Check out the demo on the original post

Browser Support and Polyfills

As of initial publication, Chromium (Google Chrome, Microsoft Edge, Brave, Arc) supports the full range of APIs described here. Firefox supports attachInternals and formAssociated but does not support ARIA and role reflection. WebKit does not support any of the new APIs, but the commits to add support have been merged, so the next Safari Technology Preview is likely to add support.

Engine	FACE	`ElementInternals`	AOM Reflection
Chromium	✅	✅	✅
Firefox	✅	✅	❌
WebKit	❌	❌	❌

The inimitable Caleb D. Williams has kindly published an ElementInternals polyfill which weighs in at ~6kb over-the-wire. Since the spec involves hooking into browser stuff which is otherwise unavailable to developers, the polyfill is not 100% spec compliant. For example, ARIA reflection is implemented by adding aria- attributes to the host element, where the spec states that they should not be added. The polyfill also adds a workaround for the custom state part of the spec, which was not covered here.

Thoughts? Corrections? Comments? Let me know on mastodon.

Let's Write a Redux Controller for Web Components

Benny Powers 🇮🇱🇨🇦 — Thu, 06 Jan 2022 22:55:21 +0000

Elliott Marquez challenged me to write a redux controller on the Lit & Friends slack.

ElliottFollow

I work on Developer experiences at Chrome and closely with the web platform

So let's get cracking!

Step 0: The Setup

First step let's make a new project and import some dependencies to help us develop.

mkdir controllers
cd controllers
git init
npm init --yes
npm i -D typescript lit
touch reducer.ts

Ok next we'll set up the controller class in reducer.ts

import type { ReactiveController, ReactiveControllerHost } from 'lit';

export class ReducerController implements ReactiveController {
  constructor(
    public host: ReactiveControllerHost,
  ) {
    host.addController(this);
  }

  hostUpdate()?: void;
}

That hostUpdate signature is just to keep typescript from complaining. 🤷.

Step 1: Reducers

Our controller essentially bolts some statefullness onto a function which takes some state T and some action A and returns some other or the same state T. So let's formalize that:

type Reducer<T, A> = (state: T, action: A) => T;

The controller should take that reducer, along with some initial state, and pin them to the class instance.

export class ReducerController<T = unknown, A = unknown> implements ReactiveController {
  public state: T;

  constructor(
    private host: ReactiveControllerHost,
    public reducer: Reducer<T, A>,
    public initialState: T,
  ) {
    this.host.addController(this);
    this.state = initialState;
  }

  hostUpdate?():void
}

Step 2: Actions

Believe it or not we're pretty much done. The last piece we need is to implement a dispatch method which takes an action A and updates the host.

dispatch(action: A): void {
  this.state = this.reducer(this.state, action);
  this.host.requestUpdate();
}

And, as Chef John would say, that's it!

If we want to use our controller, we just create it on a compatible host (like LitElement) and we're off to the races:

Live Demo

Clearing Rows with CSS Grid

Benny Powers 🇮🇱🇨🇦 — Thu, 06 Jan 2022 19:14:26 +0000

Today I completed a fun little challenge using CSS Grid.

The goal was to update a layout that relied on container elements and flexbox.

<div class="cards">
  <pfe-card id="a-1">...</pfe-card>
  <pfe-card id="a-2">...</pfe-card>
  <pfe-card id="a-3">...</pfe-card>
  <pfe-card id="a-4">...</pfe-card>
</div>
<div class="cards">
  <pfe-card id="b-1">...</pfe-card>
  <pfe-card id="b-2">...</pfe-card>
  <pfe-card id="b-3">...</pfe-card>
  <pfe-card id="b-4">...</pfe-card>
</div>

.cards {
  display: flex;
  flex-flow: row wrap;
}

.cards > * {
  margin-bottom: 15px;
  margin-right: 15px;
  min-width: 200px;
  width: calc(25% - 32px);
}

My first step was to remove the container elements and 'lift up' the flex properties into the grid container

<pfe-card id="a-1">...</pfe-card>
<pfe-card id="a-2">...</pfe-card>
<pfe-card id="a-3">...</pfe-card>
<pfe-card id="a-4">...</pfe-card>
<pfe-card id="b-1">...</pfe-card>
<pfe-card id="b-2">...</pfe-card>
<pfe-card id="b-3">...</pfe-card>
<pfe-card id="b-4">...</pfe-card>

:host {
  display: grid;
  grid-template-columns: repeat(
    auto-fill,
    minmax(
      200px,
      calc(25% - 32px)));
  grid-auto-rows: max-content;
  gap: 15px;
}

This did most of the job on its own, but there was one issue: in the original layout, card b-1 appeared in a new 'row' below the first set of cards. How could I emulate this 'row-clearing' behaviour? Using grid-column, I specified the position of the first card in the second set:

#b-1 {
  grid-column: 1/2;
}

Now, that one specific card 'resets' it's whole row, replicating the original behaviour, but with fewer non-semantic elements, and less CSS.

nice

🕎 8 Days of Web Components Tips

Benny Powers 🇮🇱🇨🇦 — Sun, 05 Dec 2021 18:10:05 +0000

In honour of Hannukah this year, I undertook to write 8 web components tips, one for each night of the festival. Tonight is the 8th and final night of the festival. The mystics said that this night combines and contains aspects of each of the seven previous nights, so I'd like to share a compilation of those tips with the dev community.

Wishing you and yours a fully Lit Hannukah!

1st night: Adding Controllers via TypeScript Decorators 🕯

Did you know you can add reactive controllers to an element via a class or field decorator? You don't even need to assign it to an instance property!

/**
 * Adds a given class to a ReactiveElement when it upgrades
 */
export function classy(classString: string): ClassDecorator {
  return function(klass) {
    if (!isReactiveElementClass(klass))
      throw new Error(`@classy may only decorate ReactiveElements.`);

    klass.addInitializer(instance => {
      // Define and add an ad-hoc controller!
      // Look, mah! No instance property!
      instance.addController({
        hostConnected() {
          instance.classList.add(classString);
        },
      });
    });
  };
}

@customElement('pirsumei-nissa') @classy('al-hanissim')
export class PirsumeiNissa extends LitElement {}

2nd night: Adding Controllers Inside Other Controllers 🕯🕯

Like a delicious sufganya (traditional holiday donut) with many fillings, a Lit component can have multiple reactive controllers, and controllers can even add other controllers

export class MutationController<E extends ReactiveElement> implements ReactiveController {
  private logger: Logger;

  mo = new MutationObserver(this.onMutation);

  constructor(public host: E, public options?: Options<E>) {
    // Add another controller
    this.logger = new Logger(this.host);
    host.addController(this);
  }

  onMutation(records: MutationRecord[]) {
    this.logger.log('Mutation', records);
    this.options?.onMutation?.(records)
  }

  hostConnected() {
    this.mo.observe(this.host, this.options?.init ?? { attributes: true, childList: true });
  }

  hostDisconnected() {
    this.mo.disconnect();
  }
}

3rd night: Web Component Context API 🕯🕯🕯

Did you know web components can have context? The protocol is based on composed events. Define providers & consumers, & share data across the DOM.

https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md

4th night: Using SASS, PostCSS, etc. 🕯🕯🕯🕯

Building #webcomponents with #SASS? (You probably don't need it but if you can't resist…) you can develop using a buildless workflow with Web Dev Server and esbuild-plugin-lit-css

Want to use #PostCSS instead for sweet-sweet future CSS syntax? No problem

5th night: Stacking Slots 🕯🕯🕯🕯🕯

Who doesn't like a piping hot stack of latkes?

Stack slots to toggle component states. Adding content into the outer slot automatically 'disables' the inner slot

State management in HTML! 🤯

Check out @westbrook's blog on the topic:

Who doesn't love some `<slot />`s?

Westbrook Johnson ・ Nov 24 '21

#html #shadowdom #customelements #a11y

6th night: Better TypeScript Imports 🕯🕯🕯🕯🕯🕯

In #TypeScript 4.5, if you set preserveValueImports, you can import the class definitions of your element dependencies without worrying that TS will elide the side-effecting value.

import { LitElement } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('lit-candle')
export class LitCandle extends LitElement {
  @property({ type: Boolean }) lit = false;

  render() {
    return this.lit ? '🕯' : ' ';
  }
}

import { LitElement, html } from 'lit';
import { customElement, property, query } from 'lit/decorators.js';
import { LitCandle } from './lit-candle.js';

@customElement('lit-menorah')
export class LitMenorah extends LitElement {
  @property({ type: Number }) night = 6;

  // Although the value of `LitCandle` isn't used, only the type
  // with `preserveValueImports`, TS 4.5 won't strip the import
  // So you can be sure that `<lit-candle>` will upgrade
  @query('lit-candle') candles: NodeListOf<LitCandle>;

  render() {
    return Array.from({ length: 8 }, (_, i) => html`
      <lit-candle ?lit="${(i + 1) <= this.night}"></lit-candle>
    `);
  }
}

live demo

7th night: GraphQL Web Components 🕯🕯🕯🕯🕯🕯🕯

Looking to add #GraphQL to your frontend? Give Apollo Elements a try. Use Apollo reactive controllers with lit+others, or try a 'functional' library like atomic

import { ApolloQueryController } from '@apollo-elements/core';
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { HelloQuery } from './Hello.query.graphql';

@customElement('hello-query')
export class HelloQueryElement extends LitElement {
  query = new ApolloQueryController(this, HelloQuery);

  render() {
    return html`
      <article class=${classMap({ skeleton: this.query.loading })}>
        <p id="error" ?hidden=${!this.query.error}>${this.query.error?.message}</p>
        <p>
          ${this.query.data?.greeting ?? 'Hello'},
          ${this.query.data?.name ?? 'Friend'}
        </p>
      </article>
    `;
  }
}

8th night: Component Interop 🕯🕯🕯🕯🕯🕯🕯🕯

You don't need to use only #lit components in your #lit app

Mix old-school #Polymer 3 components with #vue js web components. Put #stencil js Microsoft's #FAST UI on the same page

It's your party!

<!DOCTYPE html>
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.0.0-beta.61/dist/themes/light.css">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core/css/ionic.bundle.css"/>
  <script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.0.0-beta.61/dist/shoelace.js"></script>
  <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core/dist/ionic/ionic.esm.js"></script>
  <script type="module" src="https://unpkg.com/@microsoft/fast-components"></script>
  <script type="module" src="https://unpkg.com/@patternfly/pfe-datetime@1.12.2/dist/pfe-datetime.js?module"></script>
  <script type="module" src="https://unpkg.com/@material/mwc-button?module"></script>
</head>
<body>
  <sl-card>
    <pfe-datetime slot="header" type="relative" datetime="Mon Jan 2 15:04:05 EST 2010"></pfe-datetime>
    <ion-img slot="image" src="https://placekitten.com/300/200"></ion-img>
    <fast-progress-ring min="0" max="100" value="75"></fast-progress-ring>
    <mwc-button slot="footer">More Info</mwc-button>
  </sl-card>
</body>

The Next Evolution of GraphQL Front Ends

Benny Powers 🇮🇱🇨🇦 — Mon, 02 Aug 2021 14:32:20 +0000

Originally posted on the Apollo Elements blog. Read there to enjoy interactive demos.

Apollo Elements has come a long way since its first release as lit-apollo in 2017. What started as a way to build GraphQL-querying LitElements has blossomed into a multi-library, multi-paradigm project with extensive docs.

Today we're releasing the next version of Apollo Elements' packages, including a major change: introducing GraphQL Controllers, and GraphQL HTML Elements.

Reactive GraphQL Controllers

The latest version of Lit introduced a concept called "reactive controllers". They're a way to pack up reusable functionality in JavaScript classes that you can share between elements. If you've use JavaScript class mixins before (not the same as React mixins), they you're familiar with sharing code between elements. Controllers go one-better by being sharable and composable without requiring you to apply a mixin to the host element, as long as it implements the ReactiveControllerHost interface.

You can even have multiple copies of the same controller active on a given host. In the words of the Lit team, controllers represent a "has a _" relationship to the host element, where mixins represent an "is a _" relationship.

For Apollo Elements, it means now you can add many GraphQL operations to one component, like multiple queries or a query and a mutation. Here's an interactive example of the latter:

import type { TextField } from '@material/mwc-textfield';
import { ApolloQueryController, ApolloMutationController } from '@apollo-elements/core';
import { LitElement, html } from 'lit';
import { customElement, query } from 'lit/decorators.js';
import { UsersQuery, AddUserMutation } from './graphql.documents.js';
import { style } from './Users.css.js';

@customElement('users-view')
class UsersView extends LitElement {
  static styles = style;

  @query('mwc-textfield') nameField: TextField;

  users = new ApolloQueryController(this, UsersQuery);

  addUser = new ApolloMutationController(this, AddUserMutation, {
    awaitRefetchQueries: true,
    refetchQueries: [{ query: UsersQuery }],
  });

  onSubmit() { this.addUser.mutate({ variables: { name: this.nameField.value } }); }

  render() {
    const users = this.users.data?.users ?? [];
    const loading = this.users.loading || this.addUser.loading;
    return html`
      <form>
        <h2>Add a New User</h2>
        <mwc-textfield label="Name" ?disabled="${loading}"></mwc-textfield>
        <mwc-linear-progress indeterminate ?closed="${!loading}"></mwc-linear-progress>
        <mwc-button label="Submit" ?disabled="${loading}" @click="${this.onSubmit}"></mwc-button>
      </form>
      <h2>All Users</h2>
      <mwc-list>${users.map(x => html`
        <mwc-list-item noninteractive graphic="avatar">
          <img slot="graphic" ?hidden="${!x.picture}" .src="${x.picture}" role="presentation"/>
          ${x.name}
        </mwc-list-item>`)}
      </mwc-list>
    `;
  }
}

View a Live Demo of this snippet

Controllers are great for lots of reasons. One reason we've found while developing and testing Apollo Elements is that unlike the class-based API of e.g. @apollo-elements/lit-apollo or @apollo-elements/mixins, when using controllers there's no need to pass in type parameters to the host class. By passing a TypedDocumentNode object as the argument to the controller, you'll get that typechecking and autocomplete you know and love in your class template and methods, without awkward <DataType, VarsType> class generics.

If you're working on an existing app that uses Apollo Elements' base classes, not to worry, you can still import { ApolloQuery } from '@apollo-elements/lit-apollo', We worked hard to keep the breaking changes to a minimum. Those base classes now use the controllers at their heart, so go ahead: mix-and-match query components with controller-host components in your app, it won't bloat your bundles.

We hope you have as much fun using Apollo Elements controllers as we've had writing them.

Dynamic GraphQL Templates in HTML

The previous major version of @apollo-elements/components included <apollo-client> and <apollo-mutation>. Those are still here and they're better than ever, but now they're part of a set with <apollo-query> and <apollo-subscription> as well.

With these new elements, and their older sibling <apollo-mutation>, you can write entire GraphQL apps in nothing but HTML. You read that right, declarative, data-driven GraphQL apps in HTML. You still have access to the Apollo Client API, so feel free to sprinkle in a little JS here and there for added spice.

This is all made possible by a pair of libraries from the Lit team's Justin Fagnani called Stampino and jexpr. Together, they let you define dynamic parts in HTML <template> elements, filling them with JavaScript expressions based on your GraphQL data.

Here's the demo app from above, but written in HTML:

<apollo-client>
  <apollo-query>
    <script type="application/graphql" src="Users.query.graphql"></script>
    <template>
      <h2>Add a New User</h2>
      <apollo-mutation refetch-queries="Users" await-refetch-queries>
        <script type="application/graphql" src="AddUser.mutation.graphql"></script>
        <mwc-textfield label="Name"
                       slot="name"
                       data-variable="name"
                       .disabled="{{ loading }}"></mwc-textfield>
        <mwc-button label="Submit"
                    trigger
                    slot="name"
                    .disabled="{{ loading }}"></mwc-button>
        <template>
          <form>
            <slot name="name"></slot>
            <mwc-linear-progress indeterminate .closed="{{ !loading }}"></mwc-linear-progress>
            <slot name="submit"></slot>
          </form>
        </template>
      </apollo-mutation>
      <h2>All Users</h2>
      <mwc-list>
        <template type="repeat" repeat="{{ data.users ?? [] }}">
          <mwc-list-item noninteractive graphic="avatar">
            <img .src="{{ item.picture }}" slot="graphic" alt=""/>
            {{ item.name }}
          </mwc-list-item>
        </template>
      </mwc-list>
    </template>
  </apollo-query>
</apollo-client>
<script type="module" src="components.js"></script>

View a Live Demo of this snippet

There's a tonne of potential here and we're very keen to see what you come up with using these new components. Bear in mind that the stampino API isn't stable yet: there may be changes coming down the pipe in the future, but we'll do our best to keep those changes private.

More Flexible HTML Mutations

The <apollo-mutation> component lets you declare GraphQL mutations in HTML. Now, the latest version gives you more options to layout your pages. Add a stampino template to render the mutation result into the light or shadow DOM. Use the variable-for="<id>" and trigger-for="<id>" attributes on sibling elements to better integrate with 3rd-party components, and specify the event which triggers the mutation by specifying a value to the trigger attribute.

<link rel="stylesheet" href="https://unpkg.com/@shoelace-style/shoelace@2.0.0-beta.47/dist/themes/base.css">
<script src="https://unpkg.com/@shoelace-style/shoelace@2.0.0-beta.47/dist/shoelace.js?module" type="module"></script>

<sl-button id="toggle">Add a User</sl-button>

<sl-dialog label="Add User">
  <sl-input label="What is your name?"
            variable-for="add-user-mutation"
            data-variable="name"></sl-input>
  <sl-button slot="footer"
             type="primary"
             trigger-for="add-user-mutation">Add</sl-button>
</sl-dialog>

<apollo-mutation id="add-user-mutation">
  <script type="application/graphql" src="AddUser.mutation.graphql"></script>
  <template>
    <sl-alert type="primary" duration="3000" closable ?open="{{ data }}">
      <sl-icon slot="icon" name="info-circle"></sl-icon>
      <p>Added {{ data.addUser.name }}</p>
    </sl-alert>
  </template>
</apollo-mutation>
<script type="module" src="imports.js"></script>

<script type="module">
  const toggle = document.getElementById('toggle');
  const dialog = document.querySelector('sl-dialog');
  const mutation = document.getElementById('add-user-mutation');
  toggle.addEventListener('click', () => dialog.show());
  mutation.addEventListener('mutation-completed', () => dialog.hide());
</script>

Demonstrating how to use <apollo-mutation> with Shoelace web components. View a Live Demo of this snippet

Atomico support

On the heels of the controllers release, we're happy to add a new package to the roster. Apollo Elements now has first-class support for Atomico, a new hooks-based web components library with JSX or template-string templating.

import { useQuery, c } from '@apollo-elements/atomico';
import { LaunchesQuery } from './Launches.query.graphql.js';

function Launches() {
  const { data } = useQuery(LaunchesQuery, { variables: { limit: 3 } });

  const launches = data?.launchesPast ?? [];

  return (
    <host shadowDom>
      <link rel="stylesheet" href="launches.css"/>
      <ol>{launches.map(x => (
        <li>
          <article>
            <span>{x.mission_name}</span>
            <img src={x.links.mission_patch_small} alt="Badge" role="presentation"/>
          </article>
        </li>))}
      </ol>
    </host>
  );
}

customElements.define('spacex-launches', c(Launches));

FAST Behaviors

FAST is an innovative web component library and design system from Microsoft. Apollo Elements added support for FAST in 2020, in the form of Apollo* base classes. The latest release transitions to FAST Behaviors, which are analogous to Lit ReactiveControllers.

@customElement({ name, styles, template })
class UserProfile extends FASTElement {
  profile = new ApolloQueryBehavior(this, MyProfileQuery);
  updateProfile = new ApolloMutationBehavior(this, UpdateProfileMutation, {
    update(cache, result) {
      cache.writeQuery({
        query: MyProfileQuery,
        data: { profile: result.data.updateProfile },
      });
    },
  });
}

The FAST team were instrumental in getting this feature over the line, so many thanks to them.

If you're already using @apollo-elements/fast, we recommend migrating your code to behaviors as soon as you're able, but you can continue to use the element base classes, just change your import paths to /bases. These may be removed in the next major release, though.

-  import { ApolloQuery } from '@apollo-elements/fast/apollo-query';
+  import { ApolloQuery } from '@apollo-elements/fast/bases/apollo-query';

New and Improved Docs

It wouldn't be an Apollo Elements release without some docs goodies. This time, in addition to new and updated docs and guides for components and controllers, we've replaced our webcomponents.dev iframes with <playground-ide> elements. All the "Edit Live" demos on this site, including the ones in this blog post, are running locally in your browser via a service worker. Talk about serverless, amirite?

The docs also got a major upgrade care of Pascal Schilp's untiring work in the Webcomponents Community Group to get the custom elements manifest v1 published. This latest iteration of the API docs generates package manifests directly from source code, and converts them to API docs via Rocket.

SSR

As part of the release, we updated our demo apps leeway and LaunchCTL. In the case of leeway, we took the opportunity to implement extensive SSR with the help of a new browser standard called Declarative Shadow DOM. It's early days for this technique but it's already looking very promising. You can try it out in any chromium browser (Chrome, Brave, Edge, Opera) by disabling JavaScript and visiting https://leeway.apolloelements.dev.

Behind the Scenes

Bringing this release into the light involved more than just refactoring and updating the apollo-elements/apollo-elements repo. It represents work across many projects, including PRs to

Stampino and jexpr, to iron out bugs, decrease bundle size, and add features
Hybrids, to add support for reactive controllers
Atomico and Haunted, to add the useController hook which underlies useQuery and co.

Additionally, here in apollo-elements, we added the ControllerHostMixin as a way to maintain the previous element-per-graphql-document API without breaking backwards (too much). You can use this generic mixin to add controller support to any web component.

Fixes and Enhancements

The last release included support for the web components hooks library haunted, but that support hid a dirty little secret within. Any time you called a hook inside a Haunted function component, apollo elements would sneakily mix the GraphQL interface onto the custom element's prototype. It was a good hack as long as you only call one hook per component, but would break down as soon as you compose multiple operations.

With controllers at the core, and the useController hook, you can use as many Apollo hooks as you want in your elements without clobbering each other or polluting the element interface.

import { useQuery, html, component } from '@apollo-elements/haunted';
import { client } from './client.js';
import { FruitsQuery } from './Fruits.query.graphql.js';
import { VeggiesQuery } from './Veggies.query.graphql.js';

customElements.define('healthy-snack', component(function HealthySnack() {
  const { data: fruits } = useQuery(FruitsQuery, { client });
  const { data: veggies } = useQuery(VeggiesQuery, { client });
  const snack = [ ...fruits?.fruits ?? [], ...veggies?.veggies ?? [] ];
  return html`
    <link rel="stylesheet" href="healthy-snack.css"/>
    <ul>${snack.map(x => html`<li>${x}</li>`)}</ul>
  `;
}));

Demonstrating how to use multiple GraphQL hooks in a haunted component. View a Live Demo of this snippet

The same is true of the hybrids support, it now uses the controllers underneath the hood, letting you mix multiple operations in a single hybrid.

import { query, html, define } from '@apollo-elements/hybrids';
import { client } from './client.js';
import { FruitsQuery } from './Fruits.query.graphql.js';
import { VeggiesQuery } from './Veggies.query.graphql.js';

define('healthy-snack', {
  fruits: query(FruitsQuery, { client }),
  veggies: query(VeggiesQuery, { client }),
  render(host) {
    const snack = [ ...host.fruits.data?.fruits ?? [], ...host.veggies.data?.veggies ?? [] ];
    return html`
      <link rel="stylesheet" href="healthy-snack.css"/>
      <ul>${snack.map(x => html`<li>${x}</li>`)}</ul>
    `;
  }
});

Demonstrating how to use multiple GraphQL hooks in an atomico component. View a Live Demo of this snippet

Try it Out

Apollo Elements next is available in prerelease on npm. We hope you enjoy using it and look forward to seeing what you come up with.

Are you using Apollo Elements at work? Consider sponsoring the project via Open Collective to receive perks like priority support.

Narrowing the Type of Class Accessors

Benny Powers 🇮🇱🇨🇦 — Tue, 27 Jul 2021 15:03:09 +0000

Javascript class accessors let you define a function to get or set a particular value on an object.

Why would you want to do that? One popular reason is to run "side effects" in a setter. So for example say you want to make an HTTP request every time a user sets the options property on your object:

class Fetcher {
  constructor(public url = '/api', options?: RequestInit) {
    this.#options = options;
  }

  #options?: RequestInit;

  get options(): RequestInit {
    return this.#options;
  }

  set options(val: RequestInit) {
    this.#options = val;
    this.fetch();
  }

  fetch() {
    return fetch(this.url, this.options);
  }
}

By defining the options property with an accessor pair, we can run our side effects (in this case, calling fetch) in the setter.

But now let's say we want to write a Poster class that only makes POST requests. It makes sense to extend Fetcher so that we don't duplicate our work. We want to narrow the type of options, however, to only allow options where the method is POST:

type PostInit = RequestInit & { method: 'POST' };

class Poster extends Fetcher {
  declare options: PostInit;
}

What we're essentially saying with the declare keyword is "This class is exactly the same as it's parent, except that TypeScript should limit the options property to only accept PostInit objects". This should work, but...

'options' is defined as an accessor in class 'Fetcher', but is overridden here in 'Poster' as an instance property.

Oops! TypeScript complains. This change was introduced in 2020 in order to make TypeScript behave more like plain JavaScript. Indeed, TC39 decreed that class fields should have "define semantics" instead of "set semantics", which means that if we merely stripped these files of typescript syntax, our Poster class would break.

The debate over TC39's decision to use define semantics continues (even though the decision was made already), so we won't get deeper into it here, but when using typescript and "ambient declarations" like we did above with the declare keyword, we don't have the problem of our class field overriding the accessors, particularly if we don't have useDefineForClassFields turned on (which is probably a good choice anyways).

In fact, one of the three proposals which aim to fix this behaviour in typescript calls to allow fields to override accessors if they use the declare keyword.

But until that proposal, or a similar fix, is accepted, what can we do?

A Workaround Using Decorators

TypeScript field decorators have access to the class prototype. We can use one then to define our property with get and set functions. Since we're using a class private field for storage, and those are only available within a class body, let's define our decorator as a static method:

class Fetcher {
  /** @internal */
  static private o(proto: Fetcher, _: string) {
    Object.defineProperty(proto, 'options', {
      get() {
        return this.#options;
      },

      set(val) {
        this.#options = val;
        this.fetch();
      },
    });
  }

  #options?: RequestInit;

  @Fetcher.o options: RequestInit;

  constructor(public url = '/api', options?: RequestInit) {
    this.#options = options;
  }

  fetch() {
    return fetch(this.url, this.options);
  }
}

If you squint, you can still see the original outline of the class, and this version does not error when we declare our narrow type on the subclass.

Really, this is a (kind of ugly) loophole to tide us over until TypeScript decides which proposal (if any) to adopt for this pattern. Here's hoping they don't close it before then.

Footnotes

Eagle-eyed readers might object to my example:

Poster should implement it's own setter to only allow POST at run time!

They'd be right to do so. We could come up with other examples where the options object doesn't have runtime validation, or where that validation is done in other methods. In those cases, it would be right-handy to declare the narrower type on the subclass.