@greenwood/plugin-renderer-lit

Overview

A Greenwood plugin for using Lit's SSR capabilities as a custom server-side renderer instead of Greenwood's default renderer (WCC). This plugin also gives the ability to statically (pre) render entire pages and layouts to output completely static sites. For more information and complete docs on Greenwood, please visit our website.

You can see this repo for a full demo of an isomorphic Lit SSR project with SSR pages and API routes, deployed to Vercel.

This package assumes you already have @greenwood/cli installed.

Prerequisite

This packages depends on the Lit package as a peerDependency. This means you must have Lit already installed in your project. You can install anything following the 3.x release line.

# npm
$ npm -i lit

# yarn
$ yarn add lit

# pnpm
$ pnpm add lit

Installation

You can use your favorite JavaScript package manager to install this package.

# npm
$ npm i -D @greenwood/plugin-renderer-lit

# yarn
$ yarn add @greenwood/plugin-renderer-lit --dev

# pnpm
$ pnpm add -D @greenwood/plugin-renderer-lit

For pnpm, you will also want to add this to your .npmrc file

public-hoist-pattern[]=@lit-labs/*
public-hoist-pattern[]=lit-html

Usage

Add this plugin to your greenwood.config.js:

import { greenwoodPluginRendererLit } from '@greenwood/plugin-renderer-lit';

export default {
  prerender: true, // enable this flag for SSG

  plugins: [
    greenwoodPluginRendererLit()
  ]
}

Types

Types should automatically be inferred through this package's exports map, but can be referenced explicitly in both JavaScript (JSDoc) and TypeScript files if needed.

/** @type {import('@greenwood/plugin-renderer-lit').LitRendererPlugin} */

import type { LitRendererPlugin } from '@greenwood/plugin-renderer-lit';

API Routes

If you're using CSS Module Scripts and API Routes, you will need to make sure to import Lit's CSS Register Hook at the top of your function handler.

// make sure to import the register-css-hook first!
import "@lit-labs/ssr-dom-shim/register-css-hook.js";
import { render } from '@lit-labs/ssr';
import { collectResult } from '@lit-labs/ssr/lib/render-result.js'
import { html } from 'lit';
import { unsafeHTML } from 'lit/directives/unsafe-html.js';
import { getProducts } from '../../services/products.ts';
import '../../components/card/card.ts';

export async function handler() {
  const products = await getProducts();
  const body = await collectResult(render(html`
    ${
      unsafeHTML(products.map((item, idx) => {
        const { title, thumbnail } = item;

        return `
          <app-card
            title="${idx + 1}) ${title}"
            thumbnail="${thumbnail}"
          ></app-card>
        `;
      }).join(''))
    }
  `));

  return new Response(body, {
    headers: new Headers({
      'Content-Type': 'text/html'
    })
  });
}

Caveats

1. Lit SSR does not support native HTMLElement which means you will need to use LitElement as your base class in all instances where you are pre-rendering or using SSR.
2. Be aware of the known caveats as called out in the Lit SSR docs, such as:
   • Lit SSR only renders into declarative shadow roots, so you will have to keep browser support (and polyfill usage) in mind.
   • At this time, LitElement does not support async work (e.g. for connectedCallback). You can follow along with this issue and this issue from the Lit repo.
3. For constructor props support, you will have to map attributes to properties
4. Full hydration support is not available yet. See this Greenwood issue to follow along with when it will land.

Note: As LitElement only renders into Shadow Roots, for pages and layouts this plugin will extract the HTML contents of the SSR'd <template> tag and output those content into the Light DOM of your page.

Usage

Add this plugin to your greenwood.config.js:

import { greenwoodPluginRendererLit } from '@greenwood/plugin-renderer-lit';

export default {
  // ...

  plugins: [
    greenwoodPluginRendererLit()
  ]
}

Now, you can author SSR pages using Lit templates and components using Greenwood's getBody API. The below is an example of generating a template of LitElement based <app-card> web components.

// src/pages/products.js
import { html } from 'lit';
import { getProducts } from '../services/products.js';
import '../components/card.js';

export async function getBody() {
  const products = await getProducts();

  return html`
    ${
      products.map((product, idx) => {
        const { title, thumbnail } = product;

        return html`
          <app-card
            title="${idx + 1}) ${title}"
            thumbnail="${thumbnail}"
          ></app-card>
        `;
      })
    }
  `;
}

Options

Prerender

The plugin works with Greenwood's prerender configuration, allowing for the use of Lit's SSR renderer for prerendering your content.

import { greenwoodPluginRendererLit } from '@greenwood/plugin-renderer-lit';

export default {
  prerender: true,

  plugins: [
    greenwoodPluginRendererLit()
  ]
}

Keep in mind you will need to make sure your Lit Web Components are isomorphic and properly leveraging LitElement's lifecycles and browser / Node APIs accordingly for maximum compatibility and portability.

Isolation Mode

By default, this plugin sets isolation mode to true for all SSR pages. If you want to override this, just export an isolation const.

// src/pages/products.js
export const isolation = false;

See the isolation configuration docs for more information.

Hydration

In order for server-rendered components to become interactive on the client side, Lit's client-side hydration script must be included on the page. This setting is true by default, but if you want to turn it off, you can export the hydration option from your page with a value of false.

// src/pages/products.js
export const hydration = false; // disable Lit hydration scripts for this page