Eleventy plugin for rendering Lit components.
npm install @lit-labs/eleventy-plugin-litA 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
- @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:
``sh`
npm i @lit-labs/eleventy-plugin-lit
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',
],
});
};
`
Use the mode setting to tell the plugin which mode to use for rendering.'worker'
The plugin currently supports either or 'vm'.
'worker' mode (default) utilizes
worker threads
to render components in isolation.
'vm' mode utilizes vm.Module--experimental-vm-modules
for context isolation and therefore eleventy _must_ be executed with the Node flag enabled. This flag is available in12.16.0
Node versions and above.
`sh`
NODE_OPTIONS=--experimental-vm-modules eleventy
> 🚧 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.eleventy
Paths are interpreted relative to the directory from which the
command is executed.
Each .js file should be a JavaScript module (ESM) that imports lit with acustomElements.define
bare module specifier and defines a component with .
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.cjs
eleventy config file ends with the extension, and supply it aseleventy
a command line argument to .
`sh`
eleventy --config=.eleventy.cjs
1. Put all component .js files in a subdirectory with a nested package.json with{"type": "module"}
.
Use addWatchTarget to tell Eleventy
to watch for changes in your JavaScript directory:
`js`
eleventyConfig.addWatchTarget('js/');
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:
`mdGreetings
`
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:
`htmlGreetings
Hello World!
`
The element above is an HTML standard called
declarative shadow DOM. See the Declarative Shadow
DOM section below for more details.
> 🚧 Note: Expanding this section with full details on component compatibility
> is on the roadmap. Follow
> #2494 for progress and discussion.
> 🚧
There are currently a number of restrictions that determine whether a component
will be compatible with Lit pre-rendering, because not all of the component
lifecycle methods are currently invoked, and the DOM APIs that can be used in
certain lifecycle methods are restricted.
The Lit team is working on finalizing and documenting the SSR lifecycle and
restrictions, follow #2494 for more
details.
> 🚧 Note: Support for passing data as properties is on the roadmap.
> Follow #2494 for progress and
> discussion. 🚧
Data can be passed to your components by setting attributes (see the name
attribute in the example above), or passing child elements.
Lit SSR depends on _Declarative Shadow
DOM_, a browser feature that allows
Shadow DOM to be created and attached directly from HTML, without the use of
JavaScript.
As of February 2022, Chrome and Edge have native support for Declarative Shadow
DOM, but Firefox and Safari don't yet.
Therefore, unless you are developing for a very constrained environment, you
must use the Declarative Shadow DOM
Polyfill to emulate this
feature in browsers that don't yet support it.
Install the polyfill from NPM:
`sh`
npm i @webcomponents/template-shadowroot
For usage, see the example bootup strategy which
demonstrates a recommended method for efficiently loading the polyfill alongside
Lit hydration support.
> ⏱️ The Declarative Shadow DOM polyfill **must be applied after all
> pre-rendered HTML has been parsed**, because it is a one-shot operation. You
> can guarantee this timing by importing the polyfill from a type=module
> script, or by placing it at the end of your
tag.Note that even if you do not require hydration, you will still need to polyfill
Declarative Shadow DOM, otherwise your pre-rendered components will never be
displayed in some browsers.
Hydration
_Hydration_ is the process where statically pre-rendered components are upgraded
to their JavaScript implementations, becoming responsive and interactive.
Lit components can automatically hydrate themselves when they detect that a
Shadow Root has already been attached, as long as Lit's _experimental hydrate
support_ module has been installed by importing
@lit-labs/ssr-client/lit-element-hydrate-support.js.> ⏱️ The Lit hydration support module **must be loaded before Lit or any
> components that depend on Lit are imported**, because it modifies the initial
> startup behavior of the
lit-element.js module and the LitElement class.Bootup
It is important to preserve some constraints when designing a boot-up strategy
for pages that use pre-rendered Lit components. In particular:
- The Declarative Shadow DOM polyfill must wait until all HTML has been parsed.
- Lit and Lit component definition modules must wait until the experimental Lit
hydration support module has loaded.
- Lit component definition modules must wait until the Declarative Shadow DOM
polyfill to have been invoked (if it was needed for the browser).
In the following diagram, each
-> edge represents a timing sequence
constraint:`
parse load install lit
HTML polyfill hydration support
| | |
v v v
run polyfill load lit
| |
v v
load component
definitions
`$3
> 🚧 Note: The pattern described here will only work in modern browsers such as
> Firefox, Chrome, Edge, and Safari. IE11 is also supported, but will require a
> different pattern that is not yet documented here. Documenting this pattern is
> on the roadmap. Follow
> #2494 for progress and discussion.
> 🚧
The following demonstrates an example strategy for booting up a page that
contains pre-rendered Lit components with Eleventy.
The Lit team is investigating ways to simplify this bootup strategy and help you
generate it. Follow #2487 and
#2490 for progress.
Typically in Eleventy your content is written in Markdown files which delegate
the outer HTML shell to a
layout. For example hello.md could delegate to the
default.html layout like this:`markdown
---
layout: default.html
---Greetings
`The file
_includes/default.html would then contain the following:`html
rel="modulepreload"
href="/node_modules/@lit-labs/ssr-client/lit-element-hydrate-support.js"
/>
{{ content }}
`Roadmap
The following features and fixes are on the roadmap for this plugin. See the
linked issues for more details, and feel free to comment on the issues if you
have any thoughts or questions.
- [#2494] Document restrictions on SSR
compatible components.
- [#2483] Allow specifying component
definition modules in front
matter instead of the
componentModules setting.- [#2485] Provide a mechanism for
passing Eleventy data to components as
_properties_, instead of attributes.
- [#2486] Patterns and documentation
for supporting IE11.
- [#2487] Provide a mechanism for
automatically generating and inserting an appropriate hydration
configuration.
- [#2490] Simplify and optimize the
polyfill + hydration bootup strategy.
Issues and comments
If you find any bugs in this package, please file an
issue. If you have any questions or
comments, start a discussion.
Contributing
Please see CONTRIBUTING.md.
$3
-
SHOW_TEST_OUTPUT: Set to show all stdout and stderr` from spawned eleventy invocations in test cases.