Merge pull request #331 from gadget-inc/feature/imperative-rendering

Add support for imperative rendering

Author: airhorns

README.md

@@ -133,6 +133,45 @@ export const DefaultDocumentTemplate: Template = (data: TemplateData<any>) => te
 `
 ```
 
+## Imperatively rendering a component
+
+Imperative rendering allows routes to dynamically render a component based on specific conditions, instead of always rendering the same component. To do so, we still require that the component is registered to allow Vite to bundle it.
+
+Note that the route which renders the component is a normal route that doesn't need any special route options configuration.
+
+To register a component, you can do the following:
+
+```js
+// The return value needs to be passed down to the reply.render() function
+const Renderable = server.registerRenderable(require.resolve('./ImperativelyRenderablePage'))
+```
+
+And then you can render it imperatively in your routes:
+
+```js
+server.get('/imperative', async (request, reply) => {
+  return reply.render(Renderable, {
+    hostname: os.hostname(),
+    requestIP: request.ip,
+  })
+})
+```
+
+A big reason why you might want to imperatively render routes is for conditional rendering, where you only want to render if the user has permission or if some header is correctly passed. Imperative rendering works fine for routes that only sometimes use `reply.render`, and otherwise do normal `reply.send`s:
+
+```js
+server.get('/imperative/:bool', async (request: FastifyRequest<{ Params: { bool: string } }>, reply) => {
+  if (request.params.bool == 'true') {
+    return reply.render(Renderable, {
+      hostname: os.hostname(),
+      requestIP: request.ip,
+    })
+  } else {
+    return reply.redirect('/not-found')
+  }
+})
+```
+
 ## How it works
 
 - mounts a `vite` server as a fastify plugin that knows how to transform code to be run server side.

package.json

@@ -9,6 +9,7 @@
   "scripts": {
     "watch": "yarn workspace fastify-renderer watch",
     "build": "yarn workspaces run build",
+    "typecheck": "yarn workspaces run typecheck",
     "lint": "eslint \"packages/**/*.{js,ts,tsx}\"",
     "lint:fix": "prettier --loglevel warn --write \"packages/**/*.{ts,tsx}\" && eslint \"packages/**/*.{ts,tsx}\" --quiet --fix",
     "release": "yarn workspace fastify-renderer publish",
@@ -47,6 +48,7 @@
   "devDependencies": {
     "cross-env": "^7.0.3",
     "fs-extra": "^10.1.0",
-    "playwright-chromium": "^1.21.0"
+    "playwright-chromium": "^1.21.0",
+    "wds": "^0.12.0"
   }
 }

packages/fastify-renderer/package.json

@@ -15,6 +15,9 @@
   "main": "node/index.js",
   "types": "node/index.d.ts",
   "scripts": {
+    "typecheck": "run-p typecheck:*",
+    "typecheck:client": "tsc --noEmit --incremental --project src/client",
+    "typecheck:node": "tsc --noEmit --incremental --project src/node",
     "watch": "run-p watch:*",
     "watch:client-es": "tsc --watch --incremental --project src/client",
     "watch:node-cjs": "tsc --watch --incremental --project src/node",
@@ -99,7 +102,6 @@
     "react-dom": "0.0.0-experimental-4ead6b530",
     "rimraf": "^3.0.2",
     "ts-jest": "^27.1.4",
-    "ts-node": "^9.1.1",
     "typescript": "^4.6.3"
   },
   "files": [

packages/fastify-renderer/src/node/Plugin.ts

@@ -6,7 +6,7 @@ import { InlineConfig } from 'vite'
 import { Template } from './DocumentTemplate'
 import { RenderBus } from './RenderBus'
 import { ReactRenderer, ReactRendererOptions } from './renderers/react/ReactRenderer'
-import { RenderableRoute, Renderer } from './renderers/Renderer'
+import { RenderableRegistration, Renderer } from './renderers/Renderer'
 import './types' // necessary to make sure that the fastify types are augmented
 import { FastifyRendererHook, ServerEntrypointManifest, ViteClientManifest } from './types'
 
@@ -22,6 +22,8 @@ export interface FastifyRendererOptions {
   hooks?: (FastifyRendererHook | (() => FastifyRendererHook))[]
 }
 
+export type ImperativeRenderable = symbol
+
 export class FastifyRendererPlugin {
   renderer: Renderer
   devMode: boolean
@@ -33,7 +35,8 @@ export class FastifyRendererPlugin {
   hooks: (FastifyRendererHook | (() => FastifyRendererHook))[]
   clientManifest?: ViteClientManifest
   serverEntrypointManifest?: ServerEntrypointManifest
-  routes: RenderableRoute[] = []
+  renderables: RenderableRegistration[] = []
+  registeredComponents: Record<ImperativeRenderable, RenderableRegistration> = {}
 
   constructor(incomingOptions: FastifyRendererOptions) {
     this.devMode = incomingOptions.devMode ?? process.env.NODE_ENV != 'production'
@@ -105,7 +108,13 @@ export class FastifyRendererPlugin {
     }
   }
 
-  registerRoute(options: RenderableRoute) {
-    this.routes.push(options)
+  register(options: RenderableRegistration): ImperativeRenderable {
+    // If the component is not already registered, we register it and return a unique symbol for it
+    const symbol = Symbol(options.renderable)
+    this.registeredComponents[symbol] = options
+
+    this.renderables.push(options)
+
+    return symbol
   }
 }

packages/fastify-renderer/src/node/index.ts

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/require-await */
-import { FastifyInstance } from 'fastify'
+import { FastifyInstance, FastifyReply } from 'fastify'
 import 'fastify-accepts'
 import fp from 'fastify-plugin'
 import fastifyStatic from 'fastify-static'
@@ -16,8 +16,8 @@ import {
   ViteDevServer,
 } from 'vite'
 import { DefaultDocumentTemplate } from './DocumentTemplate'
-import { FastifyRendererOptions, FastifyRendererPlugin } from './Plugin'
-import { PartialRenderOptions, Render, RenderableRoute, RenderOptions } from './renderers/Renderer'
+import { FastifyRendererOptions, FastifyRendererPlugin, ImperativeRenderable } from './Plugin'
+import { PartialRenderOptions, Render, RenderableRegistration, RenderOptions } from './renderers/Renderer'
 import { kRendererPlugin, kRendererViteOptions, kRenderOptions } from './symbols'
 import { wrap } from './tracing'
 import './types' // necessary to make sure that the fastify types are augmented
@@ -75,35 +75,63 @@ const FastifyRenderer = fp<FastifyRendererOptions>(
       document: incomingOptions.document || DefaultDocumentTemplate,
     })
 
+    fastify.decorate('registerRenderable', function (this: FastifyInstance, renderable: string) {
+      const renderableRoute: RenderableRegistration = { ...this[kRenderOptions], renderable }
+      return plugin.register(renderableRoute)
+    })
+
+    const render = async (reply: FastifyReply, renderableRoute: RenderableRegistration, props: any) => {
+      if (reply.sent) return
+
+      void reply.header('Vary', 'Accept')
+      switch (reply.request.accepts().type(['html', 'json'])) {
+        case 'json':
+          await reply.type('application/json').send({ props })
+          break
+        case 'html':
+          void reply.type('text/html')
+          const render: Render<typeof props> = { ...renderableRoute, request: reply.request, reply, props }
+          await plugin.renderer.render(render)
+          break
+        default:
+          await reply.type('text/plain').send('Content type not supported')
+          break
+      }
+    }
+
+    fastify.decorateReply('render', async function (this: FastifyReply, token: ImperativeRenderable, props: any) {
+      if (!plugin.registeredComponents[token]) {
+        throw new Error(`No registered renderable was found for the provided token= ${token.toString()}`)
+      }
+      const request = this.request
+      const renderableRoute: RenderableRegistration = {
+        ...this.server[kRenderOptions],
+        pathPattern: request.url,
+        renderable: plugin.registeredComponents[token].renderable,
+        isImperative: true,
+      }
+
+      await render(this, renderableRoute, props)
+    })
+
     // Wrap routes that have the `render` option set to invoke the rendererer with the result of the route handler as the props
     fastify.addHook('onRoute', function (this: FastifyInstance, routeOptions) {
       if (routeOptions.render) {
         const oldHandler = wrap('fastify-renderer.getProps', routeOptions.handler as ServerRenderer<any>)
         const renderable = routeOptions.render
         const plugin = this[kRendererPlugin]
-        const renderableRoute: RenderableRoute = { ...this[kRenderOptions], url: routeOptions.url, renderable }
+        const renderableRoute: RenderableRegistration = {
+          ...this[kRenderOptions],
+          pathPattern: routeOptions.url,
+          renderable,
+        }
 
-        plugin.registerRoute(renderableRoute)
+        plugin.register(renderableRoute)
 
         routeOptions.handler = wrap('fastify-renderer.handler', async function (this: FastifyInstance, request, reply) {
           const props = await oldHandler.call(this, request, reply)
 
-          if (!reply.sent) {
-            void reply.header('Vary', 'Accept')
-            switch (request.accepts().type(['html', 'json'])) {
-              case 'json':
-                await reply.type('application/json').send({ props })
-                break
-              case 'html':
-                void reply.type('text/html')
-                const render: Render<typeof props> = { ...renderableRoute, request, reply, props, renderable }
-                await plugin.renderer.render(render)
-                break
-              default:
-                await reply.type('text/plain').send('Content type not supported')
-                break
-            }
-          }
+          await render(reply, renderableRoute, props)
         })
       }
     })
@@ -162,7 +190,7 @@ const FastifyRenderer = fp<FastifyRendererOptions>(
         config = await resolveConfig(fastify[kRendererViteOptions], 'serve')
       }
 
-      await plugin.renderer.prepare(plugin.routes, config, devServer)
+      await plugin.renderer.prepare(plugin.renderables, config, devServer)
     })
 
     fastify.addHook('onClose', async () => {
@@ -178,7 +206,6 @@ const FastifyRenderer = fp<FastifyRendererOptions>(
 
 module.exports = exports = FastifyRenderer
 export default FastifyRenderer
-
 export const build = async (fastify: FastifyInstance) => {
   const plugin = fastify[kRendererPlugin]
   if (!plugin) {
@@ -189,7 +216,7 @@ export const build = async (fastify: FastifyInstance) => {
 
   const clientEntrypoints: Record<string, string> = {}
   const serverEntrypoints: Record<string, string> = {}
-  for (const renderableRoute of plugin.routes) {
+  for (const renderableRoute of plugin.renderables) {
     const entrypointName = mapFilepathToEntrypointName(renderableRoute.renderable, renderableRoute.base)
     clientEntrypoints[entrypointName] = plugin.renderer.buildVirtualClientEntrypointModuleID(renderableRoute)
     serverEntrypoints[entrypointName] = plugin.renderer.buildVirtualServerEntrypointModuleID(renderableRoute)
@@ -239,3 +266,5 @@ export const build = async (fastify: FastifyInstance) => {
     JSON.stringify(virtualModulesToRenderedEntrypoints, null, 2)
   )
 }
+
+Object.assign(FastifyRenderer, { build })

packages/fastify-renderer/src/node/renderers/Renderer.ts

@@ -16,24 +16,28 @@ export type PartialRenderOptions =
   | { base: string }
   | { document: Template }
 
-/** One renderable route */
-export interface RenderableRoute extends RenderOptions {
-  url: string
+/** One renderable component registered in the system */
+export interface RenderableRegistration extends RenderOptions {
+  /** The URL path pattern this renderable will be mounted at  */
+  pathPattern?: string
+  /** The path on disk to the renderable component for SSR */
   renderable: string
+  /** If this renderable was registered for imperative rendering */
+  isImperative?: true
 }
 
 /** A unit of renderable work */
-export interface Render<Props = any> extends RenderableRoute {
+export interface Render<Props = any> extends RenderableRegistration {
   request: FastifyRequest
   reply: FastifyReply
   props: Props
 }
 
 /** An object that knows how to render */
 export interface Renderer {
-  prepare(routes: RenderableRoute[], viteOptions: ResolvedConfig, devServer?: ViteDevServer): Promise<void>
+  prepare(renderable: RenderableRegistration[], viteOptions: ResolvedConfig, devServer?: ViteDevServer): Promise<void>
   render<Props>(render: Render<Props>): Promise<void>
-  buildVirtualClientEntrypointModuleID(route: RenderableRoute): string
-  buildVirtualServerEntrypointModuleID(route: RenderableRoute): string
+  buildVirtualClientEntrypointModuleID(renderable: RenderableRegistration): string
+  buildVirtualServerEntrypointModuleID(renderable: RenderableRegistration): string
   vitePlugins(): Plugin[]
 }