@greenwood/plugin-renderer-lit

@greenwood/plugin-renderer-lit

Overview

A Greenwood plugin for using Lit's SSR capabilities as a custom server-side renderer. Although support is experimental at this time, this plugin also gives the ability to statically render entire pages and templates (instead of puppeteer) to output completely static sites.

We are still actively working on SSR features and enhancements for Greenwood as part of our 1.0 release so please feel free to test it out and report your feedback. 🙏

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 2.x release line.

# npm
$ npm install lit --dev

# yarn
$ yarn add lit --dev

Installation

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

# npm
npm install @greenwood/plugin-renderer-lit --save-dev

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

Usage

Add this plugin to your greenwood.config.js.

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

export default {
  ...

  plugins: [
    greenwoodPluginRendererLit()
  ]
}

Now, you can write some SSR routes using Lit including all the available APIs. The below example uses the standard SimpleGreeting component from the Lit docs by also using a LitElement as the default export!

import { html, LitElement } from 'lit';
import './path/to/greeting.js';

export default class ArtistsPage extends LitElement {

  constructor() {
    super();
    this.artists = [{ /* ... */ }];
  }

  render() {
    const { artists } = this;

    return html`
      ${
        artists.map((artist) => {
          const { id, name, imageUrl } = artist;

          return html`
            <a href="/artists/${id}" target="_blank">
              <simple-greeting .name="${name}"></simple-greeting>
            </a>

            <img src="${imageUrl}" loading="lazy"/>

            <br/>
          `;
        })
      }
    `;
  }
}

// for now these are needed for the Lit specific implementations
customElements.define('artists-page', ArtistsPage);
export const tagName = 'artists-page';

Caveats

There are a few considerations to take into account when using a LitElement as your page component:

• Lit SSR only renders into declarative shadow roots, so you will have to keep browser support and polyfill usage in mind.
• Depending on your use case, SSR bundling may break due to bundle chunking and code splitting by Rollup, which we are hoping to correct ASAP.
• At this time, LitElement does not support async work which makes data fetching in pages a bit of challenge. You can follow along with this issue in the Lit repo.

You can see a work (in progress) demo of using Lit SSR (with Serverless!) here.

Options

Prerender (experimental)

The plugin provides a setting that can be used to override Greenwood's default prerender implementation which uses WCC, to use Lit instead.

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

export default {
  ...

  plugins: [
    greenwoodPluginRendererLit({
      prerender: true
    })
  ]
}

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.