Lit Integration

The @ecopages/lit package provides seamless integration with Lit, enabling the use of Lit components and reactive properties within the Ecopages framework.

Installation

To install the Lit integration plugin, run the following command in your project directory:

bunx jsr add @ecopages/lit

Usage

To incorporate the Lit integration into your Ecopages project, follow these steps:

1. Import the litPlugin in your Ecopages configuration file:

import { ConfigBuilder } from '@ecopages/core';
import { litPlugin } from '@ecopages/lit';

2. Add the litPlugin to your configuration:

const config = await new ConfigBuilder()
	.setRootDir(import.meta.dir)
	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
	.setIntegrations([litPlugin()])
	.build();
 
export default config;

Creating Components with Lit

Creating Components with Lit

Once the Lit integration is set up, you can create components. Ecopages provides a StyledMixin to easily apply styles to your Lit components.

Thanks to the Ecopages PostCSS processor, you can import CSS files directly as strings, which is perfect for Lit's shadow DOM styles.

import { StyledMixin } from '@ecopages/lit/styled-mixin';
import { html, LitElement } from 'lit';
import { customElement, property } from 'lit/decorators.js';
// Styles are imported as a string thanks to the PostCSS processor
import styles from './lit-counter.css';
 
@customElement('lit-counter')
export class LitCounter extends StyledMixin(LitElement, [styles]) {
	@property({ type: Number }) count = 0;
 
	decrement() {
		if (this.count > 0) this.count--;
	}
 
	increment() {
		this.count++;
	}
 
	override render() {
		return html`
			<button @click=${this.decrement}>-</button>
			<span>${this.count}</span>
			<button @click=${this.increment}>+</button>
		`;
	}
}

Create the Component Wrapper

To properly integrate the Lit component into Ecopages (handling dependencies and lazy loading), create a wrapper using eco.component.

import { eco } from '@ecopages/core';
import './lit-counter.script';
 
export const LitCounter = eco.component({
	dependencies: {
		scripts: ['lit-counter.script.ts'],
	},
	render: (props: { count: number }) => html`
		<lit-counter count=${props.count}></lit-counter>
	`,
});

This wrapper ensures that the script is loaded when needed and provides a typed interface for using the component in pages.

Using Lit Components in Pages

To use Lit components in your pages, import the wrapper and include it in your page using eco.page.

import { LitCounter } from '@/components/lit-counter';
import { BaseLayout } from '@/layouts/base-layout';
import { eco, html } from '@ecopages/core';
 
export default eco.page({
	metadata: () => ({
		title: 'Home page',
		description: 'This is the homepage of the website',
	}),
	dependencies: {
		components: [BaseLayout, LitCounter],
	},
	render: () =>
		html`${BaseLayout({
			class: 'main-content',
			children: html`
				<h1>Home</h1>
				${LitCounter({ count: 8 })}
			`,
		})}`,
});

Key Features

2. Server-Side Rendering (SSR): Lit components are server-side rendered by default in Ecopages, except when used within MDX files (currently).
3. Reactive Properties: Utilize Lit's reactive properties for efficient updates.
4. Declarative Templates: Use Lit's html template literal for creating component templates.
5. Separation of Concerns: Styles are written in separate CSS files and linked via the component's config.

Best Practices

1. Component Naming: Use kebab-case for custom element names (e.g., lit-counter).
2. Separate CSS Files: Keep styles in separate CSS files to improve maintainability.
3. Config Object: Always include the config object with any necessary dependencies.
4. Type Declarations: Include type declarations for custom elements to improve TypeScript support.

Integration with Other Plugins

The Lit integration works well with other Ecopages plugins. For example, you can use it alongside the kitajs plugin to create reusable components in a jsx style.

import { ConfigBuilder } from '@ecopages/core';
import { litPlugin } from '@ecopages/lit';
import { kitajsPlugin } from '@ecopages/kitajs';
 
const config = await new ConfigBuilder()
	.setRootDir(import.meta.dir)
	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
	.setIntegrations([litPlugin(), kitajsPlugin()])
	.build();
 
export default config;

By leveraging the Lit integration, you can create powerful, reactive components within your Ecopages project, combining the efficiency of static site generation with the interactivity of modern web components.