Build-time rendering

Build-time rendering (BTR) renders a route to HTML during the build process and in-lines critical CSS and assets needed to display the initial view. This allows Dojo to pre-render the initial HTML used by a route and inject it directly into the page immediately, resulting in many of the same benefits of server side rendering (SSR) such as performance gains and search engine optimization without the complexities of SSR.

Using BTR

First make sure index.html includes a DOM node with an id attribute. This node will be used by Dojo’s virtual DOM to compare and render the application’s HTML. BTR requires this setup so it can render the HTML generated at build time. This creates a very fast and responsive initial rendering of the route.

index.html

  1. <!DOCTYPE html>
  2. <html lang="en-us">
  3.     <head>
  4.         <title>sample-app</title>
  5.         <meta name="theme-color" content="#222127" />
  6.         <meta name="viewport" content="width=device-width, initial-scale=1" />
  7.     </head>
  8.     <body>
  9.         <div id="app"></div>
  10.     </body>
  11. </html>

The application should then be mounted to the specified DOM node:

main.ts

  1. const r = renderer(() => w(App, {}));
  2. const domNode = document.getElementById('app') as HTMLElement;
  3. r.mount({ registry, domNode });

The project’s .dojorc configuration file should then be updated with the id of the root DOM node and routes to render at build time.

.dojorc

  1. {
  2.     "build-app": {
  3.         "build-time-render": {
  4.             "root": "app",
  5.             "paths": [
  6.                 "#home",
  7.                 {
  8.                     "path": "#comments/9999",
  9.                     "match": ["#comments/.*"]
  10.                 }
  11.             ]
  12.         }
  13.     }
  14. }

This configuration describes two routes. A home route and a more complex comments route. The comments route is a more complex route with parameter data. A match is used to make sure that the build-time HTML created for this route is applied to any route that matches the regular expression.

BTR generates a screenshot for each of the paths rendered during build in the ./output/info/screenshots project directory.

History manager

Build time rendering supports applications that use either the @dojo/framework/routing/history/HashHistory or @dojo/framework/routing/history/StateHistory history managers. When using HashHistory, ensure that all paths are prefixed with a # character.

build-time-render feature flag

Build time rendering exposes a build-time-render feature flag that can be used to skip functionality that cannot be executed at build time. This can be used to avoid making fetch calls to external systems and instead provide static data that can be used to create an initial render.

  1. if (has('build-time-render')) {
  2.     const response = await fetch(/* remote JSON */);
  3.     return response.json();
  4. } else {
  5.     return Promise.resolve({
  6.         /* predefined Object */
  7.     });
  8. }

Dojo Blocks

Dojo provides a blocks system which can execute code in Node.js as part of the build time rendering process. The results from the execution are written to a cache that can then be transparently used in the same way at runtime in the browser. This opens up new opportunities to use operations that might be not possible or perform poorly in a browser.

For example, a Dojo Block module could read a group of markdown files, transform them into VNodes, and make them available to render in the application, all at build time. The result of this Dojo Block module is then cached into the application bundle for use at runtime in the browser.

A Dojo Block module gets used like any middleware or meta in a Dojo widget. For the Dojo build system to be able to identify and run a block module there are three requirements that must be met:

  1. The module must have a .block suffix, for example src/readFile.block.ts.
  2. The Block must only have a single default export
  3. Return values from blocks (from a promise resolution or as an immediate return) must be serializable to json

Other than these requirements there is no configuration or alternative authoring pattern required.

For example, a block module could read a text file and return the content to the application.

src/readFile.block.ts

  1. import * as fs from 'fs';
  2. import { resolve } from 'path';
  4. export default (path: string) => {
  5.     path = resolve(__dirname, path);
  6.     return fs.readFileSync(path, 'utf8');
  7. };

src/widgets/MyBlockWidget.tsx

  1. import { create, tsx } from '@dojo/framework/core/vdom';
  2. import block from '@dojo/framework/core/middleware/block';
  4. import readFile from '../readFile.block';
  6. const factory = create({ block });
  8. export default factory(function MyBlockWidget({ middleware: { block } }) {
  9.     const message = block(readFile)('../content/hello-dojo-blocks.txt');
  10.     return <div>{message}</div>;
  11. });

This widget runs the src/readFile.block.ts module at build time to read the contents of the given file to be used in the widget’s render output.