Skip to content

Commit

Permalink
update Renderer plugin docs
Browse files Browse the repository at this point in the history
  • Loading branch information
thescientist13 committed Jun 25, 2023
1 parent e2b7067 commit 7f8d9d7
Showing 1 changed file with 9 additions and 10 deletions.
19 changes: 9 additions & 10 deletions www/pages/plugins/renderer.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ index: 4

## Renderer

Renderer plugins allow users to customize how Greenwood server renders (and prerenders) your project. By default, Greenwood just supports using [(template) strings](/docs/server-rendering/) to return static HTML for the content and template of your server side routes. For example, using [Lit SSR](https://github.com/lit/lit/tree/main/packages/labs/ssr) to render Lit Web Components server side.
Renderer plugins allow users to customize how Greenwood server renders (and prerenders) your project. By default, Greenwood supports using [**WCC** or (template) strings](/docs/server-rendering/) to return static HTML for the content and template of your server side routes. With this plugin for example, you can use [Lit's SSR](https://github.com/lit/lit/tree/main/packages/labs/ssr) to render your Lit Web Components server side instead.

### API

Given that rendering Web Components on the server side often involves implementations needing to patch the NodeJS globals space or more complex needs like running an entire headless browser, Greenwood provides a couple ways to manage the rendering lifecycle.
This plugin expects to be given a path to a module that exports a function to execute the SSR content of a page by being given its HTML and related scripts. For local development Greenwood will run this in a `Worker` thread for live reloading, and use it standalone for production bundling and serving.

```js
const greenwoodPluginMyCustomRenderer = (options = {}) => {
Expand All @@ -20,7 +20,7 @@ const greenwoodPluginMyCustomRenderer = (options = {}) => {
name: 'plugin-renderer-custom',
provider: () => {
return {
workerUrl: new URL('./my-ssr-route-worker.js', import.meta.url),
executeModuleUrl: new URL('./execute-route-module.js', import.meta.url),
prerender: options.prerender
};
}
Expand All @@ -33,19 +33,18 @@ export {
```
#### Options
- `workerUrl` (recommended) - URL to the location of a file with a worker thread implementation to use for rendering.
- `customUrl` - URL to a file that has a `default export` of a function for handling the _prerendering_ lifecyle of a Greenwood build, and running the provided `callback` function
- `executeModuleUrl` (recommended) - `URL` to the location of a file with the SSR rendering implementation
- `customUrl` - `URL` to a file that has a `default export` of a function for handling the _prerendering_ lifecyle of a Greenwood build, and running the provided `callback` function
- `prerender` (optional) - Flag can be used to indicate if this custom renderer should be used to statically [prerender](/docs/configuration/#prerender) pages too.
## Examples
### Workers
### Default
The recommended Greenwood API for executing server rendered code is in a [Worker](https://nodejs.org/api/worker_threads.html) thread, to avoid global namespace and API collisions.
Each worker is expected to implement [the API](/docs/server-rendering/#api) of `default export`, `getBody`, `getTemplate`, and `getFrontmatter`.
The recommended Greenwood API for executing server rendered code is in a function that is expected to implement any combination of [these APIs](/docs/server-rendering/#api); `default export`, `getBody`, `getTemplate`, and `getFrontmatter`.
You can follow the [WCC default implementation for Greenwood](https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/src/lib/ssr-route-worker.js) as a reference.
You can follow the [WCC default implementation for Greenwood](https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/src/lib/execute-route-module.js) as a reference.
### Custom Implementation
This option is useful for exerting full control over the rendering lifecycle. You can follow [Greenwood's implementation for Puppeteer](https://github.com/ProjectEvergreen/greenwood/blob/master/packages/plugin-renderer-puppeteer/src/puppeteer-handler.js) as a reference.
This option is useful for exerting full control over the rendering lifecycle, like running a headless browser. You can follow [Greenwood's implementation for Puppeteer](https://github.com/ProjectEvergreen/greenwood/blob/master/packages/plugin-renderer-puppeteer/src/puppeteer-handler.js) as a reference.

0 comments on commit 7f8d9d7

Please sign in to comment.