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

Once the Lit integration is set up, you can create components using Lit's syntax and the EcoWebComponent class. Here's an example of a Lit component using ghtml:

import { html } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { EcoWebComponent } from '@ecopages/lit';

@customElement('lit-counter')
export class LitCounter extends EcoWebComponent {
  @property({ type: Number })
  count = 0;

  render() {
    return html`
      <div>
        <p>Count: \${this.count}</p>
        <button @click=\${this._decrement}>-</button>
        <button @click=\${this._increment}>+</button>
      </div>
    `;
  }

  private _decrement() {
    this.count--;
  }

  private _increment() {
    this.count++;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'lit-counter': LitCounter;
  }
}

Note that styles are defined in a separate CSS file, promoting separation of concerns:

lit-counter {
  display: block;
  padding: 16px;
  max-width: 800px;
}

p {
  font-size: 18px;
}

button {
  font-size: 16px;
  padding: 5px 10px;
  margin: 0 5px;
}

Define the config

To properly define the config for the component and avoid issues related to multiple definitions, you should use the EcoWebComponent type.

import type { EcoWebComponent } from '@ecopages/core';
import './lit-counter.script';

export const LitCounter: EcoWebComponent = {
  config: {
    importMeta: import.meta,
    dependencies: {
      scripts: ['lit-counter.script.ts'],
    },
  },
};

As you can see we don't need to define it on the function that creates the component, due the fact we do not need it. Also remember to do not include the stylesheet in the config, because it will be included automatically by the component itself.

Using Lit Components in Pages

To use Lit components in your pages, import them and include them in your HTML template, please remember to use the .lit.ts extension.

import { LitCounter } from '@/components/lit-counter';
import { BaseLayout } from '@/layouts/base-layout';
import { type EcoComponent, type GetMetadata, html, resolveComponentsScripts } from '@ecopages/core';

export const getMetadata: GetMetadata = () => ({
  title: 'Home page',
  description: 'This is the homepage of the website',
});

const HomePage: EcoComponent = () =>
  html`${BaseLayout({
    class: 'main-content',
    children: html\`
      <h1>Home</h1>
      <lit-counter count="8"></lit-counter>
    `,
  })}`;

HomePage.config = {
  importMeta: import.meta,
  dependencies: {
    components: [BaseLayout, LitCounter],
  },
};

export default HomePage;

Key Features

1. EcoWebComponent: Extend from EcoWebComponent to create Lit components that integrate seamlessly with Ecopages.
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 importMeta and 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 and EcoWebComponent, you can create powerful, reactive components within your Ecopages project, combining the efficiency of static site generation with the interactivity of modern web components.