@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 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 3.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

Caveats

1. Please familiarize yourself with some of the caveats called out in the Lit docs, like:
   • 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. You can follow along with this issue in the Lit repo.
2. Lit only supports templates on the server side for HTML only generated content, thus Greenwood's getBody API must be used. We would love for server only components to be a thing though!
3. Full hydration support is not available yet. See this Greenwood issue to follow along when it will land

See this repo for a full demo of isomorphic Lit SSR with SSR pages and API routes deployed to Vercel serverless functions.

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 '../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>
        `;
      })
    }
  `;
}

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.

Options

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

Prerender

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.