Elena + Eleventy Example

A minimal example demonstrating how to use Elena web components inside an Eleventy static site.

What is Elena?

Elena is a lightweight (2kB) library for building Progressive Web Components that work natively in the browser. This example uses both @elenajs/core and @elenajs/components, an example component library built on top of Elena.

What This Example Demonstrates

All examples live in src/index.njk and cover:

• Variants: default, primary, and danger button styles
• Interactive counter: vanilla JS click handlers driving state
• Dynamic attribute binding: cycling through variants imperatively

Prerequisites

• Node.js v20+
• pnpm v10+

Getting Started

# Install dependencies
pnpm install

# Start the development server
pnpm start

Open http://localhost:8080 in your browser.

Available Scripts

Command	Description
pnpm start	Start the Eleventy dev server
pnpm build	Build for production

Project Structure

src/
└── index.njk          # Nunjucks template, all Elena examples live here
eleventy.config.js     # Eleventy configuration
package.json           # Dev dependencies and scripts
README.md              # This file

How Elena Web Components Are Loaded

@elenajs/components is installed as an npm dependency. Eleventy copies the bundle to the output directory via addPassthroughCopy in eleventy.config.js:

eleventyConfig.addPassthroughCopy({
  "node_modules/@elenajs/components/dist/bundle.js": "assets/bundle.js",
  "node_modules/@elenajs/components/dist/bundle.css": "assets/bundle.css",
});

Then referenced in the template:

<script src="/assets/bundle.js" type="module"></script>
<link rel="stylesheet" href="/assets/bundle.css" />

This registers all Elena web components globally, making them available as standard HTML tags.

Server-Side Rendering

@elenajs/ssr pre-renders Elena components at build time so their inner HTML is present in the static output before the browser loads any JavaScript.

Warning

@elenajs/ssr is an experimental package and not yet ready for production use. APIs may change without notice.

Install the package:

npm install @elenajs/ssr

Then add a transform in eleventy.config.js:

import { ssr, register } from "@elenajs/ssr";
const { Button, Stack } = await import("@elenajs/components");

register(Button, Stack);

export default function (eleventyConfig) {
  eleventyConfig.addTransform("elena-ssr", (content, outputPath) => {
    if (outputPath?.endsWith(".html")) {
      return ssr(content);
    } else {
      return content;
    }
  });
}

register tells the SSR renderer which components to expand. ssr walks the HTML, calls each component's render() method, and marks the element with a hydrated attribute so the client-side component knows not to re-render on load.