@lit-labs/eleventy-plugin-lit

A plugin for Eleventy that pre-renders
Lit web components at build time, with optional hydration.


> [!WARNING]
>
> This package is part of Lit Labs. It
> is published in order to get feedback on the design and may receive breaking
> changes or stop being supported.
>
> Please read our Lit Labs documentation
> before using this library in production.
>
> Give feedback: https://github.com/lit/lit/discussions/3356

Contents

- @lit-labs/eleventy-plugin-lit
- Contents
- Setup
- Install
- Register plugin
- Configure mode
- Configure component modules
- Watch mode
- Usage
- Component compatibility
- Passing data to components
- Declarative Shadow DOM
- Polyfill
- Hydration
- Bootup
- Example bootup strategy
- Roadmap
- Issues and comments
- Contributing
- Testing environment variables:

Setup

$3

``sh
npm i @lit-labs/eleventy-plugin-lit
`

$3

Edit your .eleventy.js config file to register the Lit plugin:


`js
const litPlugin = require('@lit-labs/eleventy-plugin-lit');

module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(litPlugin, {
mode: 'worker',
componentModules: [
'js/demo-greeter.js',
'js/other-component.js',
],
});
};
`


$3

Use the mode setting to tell the plugin which mode to use for rendering.
The plugin currently supports either 'worker' or 'vm'.

'worker' mode (default) utilizes
worker threads
to render components in isolation.

'vm' mode utilizes vm.Module
for context isolation and therefore eleventy _must_ be executed with the
--experimental-vm-modules Node flag enabled. This flag is available in
Node versions 12.16.0 and above.

`sh
NODE_OPTIONS=--experimental-vm-modules eleventy
`

$3

> 🚧 Note: Support for specifying component modules in Eleventy front matter is
> on the roadmap. Follow
> #2494 for progress and discussion. 🚧

Use the componentModules setting to tell the plugin where to find the
definitions of your components.

Pass an array of paths to .js files containing Lit component definitions.
Paths are interpreted relative to the directory from which the eleventy
command is executed.

Each .js file should be a JavaScript module (ESM) that imports lit with a
bare module specifier and defines a component with customElements.define.

Note that in 'worker' mode, Node determines the module system
accordingly,
and as such care must be taken to ensure Node reads them as ESM files
while still reading the eleventy config file as CommonJS.

Some options are:

1. Add {"type": "module"} to your base package.json, make sure the
eleventy config file ends with the .cjs extension, and supply it as
a command line argument to eleventy.

`sh
eleventy --config=.eleventy.cjs
`

1. Put all component .js files in a subdirectory with a nested package.json with
{"type": "module"}.

$3

Use addWatchTarget to tell Eleventy
to watch for changes in your JavaScript directory:

`js
eleventyConfig.addWatchTarget('js/');
`

Usage

Whenever you use a custom element in your Eleventy Markdown and HTML files,
@lit-labs/eleventy-plugin-lit will automatically render its template and
styles directly into your HTML.

For example, given a markdown file hello.md:

`md


Greetings


`

And a component definition js/demo-greeter.js:


`js
import {LitElement, html, css} from 'lit';

class DemoGreeter extends LitElement {
static styles = css
b { color: red; }
;

static properties = {
name: {},
};

render() {
return htmlHello ${this.name}!;
}
}
customElements.define('demo-greeter', DemoGreeter);
`


Then the Eleventy will produce greeting/index.html:


`html


Greetings



Hello World!

`


The