Document the document template option

Author: airhorns

README.md

@@ -3,13 +3,17 @@
 ![Build Status](https://github.com/gadget-inc/fastify-renderer/workflows/ci/badge.svg)
 [![NPM version](https://img.shields.io/npm/v/fastify-renderer.svg?style=flat)](https://www.npmjs.com/package/fastify-renderer)
 
-`fastify-renderer` renders client side JavaScript applications on the server to improve the user experience.
+`fastify-renderer` renders client side JavaScript applications on the server to improve user experience. `fastify-renderer` is a standard Fastify plugin that mounts into an existing fastify application, so it's easy to use for only some routes.
 
-- It renders client side apps server side with minimal setup
-- Supports optional async work ahead of time using handy server side bits like a database connection or session stored in redis
-- Serves server side props to client side pages as the navigations happen client side
-- Control things outside the inner application like the `<head/>` tag when server rendering
+`fastify-renderer` works similarly to `next.js` and other SSR frameworks, where the first pageload a user makes is server side rendered, and then a client side app is booted. Subsequent navigations are handled client side, where the client makes a `fetch` call to retrieve the next set of `props` for the next page as JSON data, instead of re-rendering the whole page server side.
 
+Features:
+
+- React SSR for fastify using `vite`
+- Allows async work ahead of time to produce props for the page, which means you can use a database connection, redis, or whatever else you have server side in Fastify
+- Support for rich React component layouts wrapping each page
+- Support for fastify plugin encapsulation contexts, so can be used to support different "areas" of an app within the same fastify server
+- Support for managing the full document shape using EJS templates
 
 ## Installation
 
@@ -22,7 +26,6 @@ yarn install fastify-renderer
 
 ## Registering the plugin
 
-
 ```js
 import fastify from 'fastify'
 import renderer from 'fastify-renderer'
@@ -31,7 +34,40 @@ const server = fastify()
 server.register(renderer)
 ```
 
+After registering the plugin, you need to set a render config for a Fastify encapsulation context.
+
+```js
+// at the root, you can set the render config for the whole server
+server.setRenderConfig({
+  layout: '../client/Layout.jsx',
+})
+
+// or within a context, you can set the render config for just routes defined in that context
+server.register(async (server) => {
+  server.setRenderConfig({
+    base: '/auth',
+    layout: '../client/auth/AuthLayout',
+  })
+
+  server.get('/auth/login', { render: require.resolve('../client/auth/LoginPage') }, async (request) => ({}))
+})
+```
+
+## Rendering from routes
+
+Once the plugin is registered, any route in your Fastify application can render components. To make a route render a component, pass a component path as the `render` option to the route options:
+
+```js
+server.get('/sample-route', { render: require.resolve('../client/ExampleComponent') }, async (_request) => {
+  const props = { hello: 'world' }
+  return props
+})
+```
+
+Unlike a normal Fastify route handler, render route functions don't use `reply.send` to return HTML content. Instead, your route handler function should return a `props` object. This `props` object will be passed to the rendered component when being rendered server side, and will be fetched from this route and passed to the component when being rendered client side.
+
 ### Configuration options
+
 You can optionally provide configuration options to the plugin:
 
 - `renderer` - Object that provides the rendering options
@@ -40,30 +76,65 @@ You can optionally provide configuration options to the plugin:
 - `vite` - Vite [InlineConfig](https://vitejs.dev/guide/api-javascript.html#inlineconfig) options
 - `base` - The base path we want our renderer to use
 - `layout` - The path to a layout component inside of which other routes will be rendered
-- `document` - HTML template inside of which everything is rendered
+- `document` - HTML template inside of which everything is rendered. The `template` option accepts a function which should return a `ReadableStream` to produce the output HTML.
 - `devMode` - Boolean, when true a vite devServer is created
 - `outDir` - The directory where the files generated by the Vite build will be created
 - `assetsHost` - The host url from which files will be accessible to the browser
-- `hooks` - Array of FastifyRendererHook 
-  - `name` - Optional string value 
+- `hooks` - Array of FastifyRendererHook
+  - `name` - Optional string value
   - `heads` - Function that will return html tags to be appended to the document head tag
   - `tails` - Function that will return html tags to be appended to the document body tag
   - `transform` - Function that will be run to transform the root react element
   - `postRenderHeads` - Function (called after render) that will return html tags to be appended to the document head tag. Useful when injecting styles that rely on rendering first.
 
+The plugin will render the component server side and return it, where as the route handler will return the props to the frontend when needed.
 
-## Setting up a route
-To set up a route, you can do the following:
-```js
-  server.get('/sample-route', { render: require.resolve('./Component') }, async (_request) => {
-    const props = { hello: 'world' }
-    return props
-  })
+#### Controlling the document template
+
+The raw HTML wrapper for each SSR page can be controlled with the `document` option passed at the root level plugin config or with `.setRenderConfig`. The `document` option accepts a function which is given render data, and should return a `ReadableStream` object for piping to the browser. We use a streaming interface in order to stream the result efficiently to the browser before the whole render is complete.
+
+The function is passed a `data` object which should be used for interpolating values into your output stream. Here's the shape of the `data` object:
+
+```typescript
+/** Data passed to the template function by the renderer */
+interface TemplateData<Props> {
+  /** The content for including in the `<head/>` tag of the rendered document */
+  head: NodeJS.ReadableStream
+  /** The content for including after the app just before the `</body>` tag of the rendered document */
+  tail: NodeJS.ReadableStream
+  /** The main content for the app */
+  content: string | NodeJS.ReadableStream
+  /** The props object generated by the route handler for this render */
+  props: Props
+}
 ```
-The plugin will render the component server side and return it, where as the route handler will return the props to the frontend when needed.
 
+Usually, the `stream-template` package is used for this for super easy interpolation of streams.
+
+Here's the default template source:
+
+```typescript
+import template from 'stream-template'
+
+export const DefaultDocumentTemplate: Template = (data: TemplateData<any>) => template`
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${data.props.title || 'Fastify Renderer App'}</title>
+    ${data.head}
+  </head>
+  <body>
+    <div id="fstrapp">${data.content}</div>
+    ${data.tail}
+  </body>
+</html>
+`
+```
 
 ## How it works
+
 - mounts a `vite` server as a fastify plugin that knows how to transform code to be run server side.
 - provides renderers that use vite for react and other popular frameworks (Currently only React is supported)
 - provides a convention for async ahead of time work to pass data into renderers
@@ -76,7 +147,7 @@ The goal of fastify-renderer is to bring a great developer/user experience and i
 - next.js has a great developer experience but blocks the main thread when rendering react.
 - next.js uses express and webpack underneath, both of which have much better performing alternatives
 - next.js must be both the bundler and the server, it's hard to mount it into an existing system like fastify and play nice with all the other plugins you might want to use when doing :gasp: server side rendered :gasp: applications
-- vite is awesome but also wants to be the server and keep the frontend entirely seperate from the backend
+- vite is awesome but also wants to be the server and keep the frontend entirely separate from the backend
 - server side rendering is hard and reinventing that wheel is no fun
 - hot reloading in development is hard and reinventing that wheel is no fun
 - bundling for production is hard and reinventing that wheel is no fun
@@ -86,8 +157,8 @@ The goal of fastify-renderer is to bring a great developer/user experience and i
 
 - [Navigating between routes from different Fastify contexts](./docs/fastify-contexts)
 
-
 ## Roadmap
+
 - Add support for rendering outside the main thread by using Piscina.js
 - Add support for Vue and other frontend frameworks
 

packages/fastify-renderer/src/node/DocumentTemplate.tsx

@@ -2,9 +2,13 @@ import template from 'stream-template'
 
 /** Data passed to the template function by the renderer */
 export interface TemplateData<Props> {
+  /** The content for including in the `<head/>` tag of the rendered document */
   head: NodeJS.ReadableStream
+  /** The content for including after the app just before the `</body>` tag of the rendered document */
   tail: NodeJS.ReadableStream
+  /** The main content for the app */
   content: string | NodeJS.ReadableStream
+  /** The props object generated by the route handler for this render */
   props: Props
 }