Configuration Options

Relevant source files

The following files were used as context for generating this wiki page:

• src/config.ts
• src/rendertron.ts
• README.md
• middleware/src/middleware.ts
• middleware/README.md
• src/renderer.ts

Rendertron's behavior can be customized through a config.json file for the core rendering service and through an options object for the Express middleware. This allows for fine-grained control over aspects like rendering timeouts, viewport dimensions, caching mechanisms, and which requests get proxied for server-side rendering.

The core service configuration primarily affects the Puppeteer instance and the Koa server it runs on. The middleware configuration is designed for developers integrating Rendertron into their own applications, allowing them to define rules for when to invoke the rendering service.

Rendertron Service Configuration

The main Rendertron service is configured via a config.json file located in the project's root directory. The service loads these settings at startup to modify its default behavior.

Sources: README.md:112-113, src/config.ts:18-20

Configuration Loading Process

Configuration is managed by the ConfigManager class. On initialization, it checks for the existence of config.json. If the file is found, its contents are merged with a set of default values. The PORT environment variable can also override the configured port.

This diagram illustrates the configuration loading flow when the service starts.

Configuration Parameters

The following options can be set in the config.json file.

Option	Type	Default Value	Description
datastoreCache	boolean	false	If true, enables caching of rendered pages using Google Cloud Datastore.
timeout	number	10000	The timeout in milliseconds for rendering a target page.
port	string	'3000'	The port for the Rendertron service to listen on. Overridden by the PORT environment variable.
width	number	1000	The default viewport width in pixels for rendering.
height	number	1000	The default viewport height in pixels for rendering.

Sources: src/config.ts:28-36, README.md:114-119

The Config type and default values are defined in src/config.ts.

// src/config.ts:23-29
export type Config = {
    datastoreCache: boolean;
    timeout: number;
    port: string;
    width:number;
    height:number;
};

// src/config.ts:32-38
export class ConfigManager {
    public static config: Config = {
        datastoreCache: false,
        timeout: 10000,
        port: '3000',
        width: 1000,
        height: 1000,
    };

Caching

When datastoreCache is set to true, the Rendertron service enables the DatastoreCache middleware. This intercepts render requests and serves a cached version from Google Cloud Datastore if available, bypassing the full rendering process.

Sources: src/rendertron.ts:50-54

Express Middleware Configuration

For applications using Express.js, the rendertron-middleware package provides a way to conditionally proxy requests to a Rendertron instance. The middleware is configured by passing an options object to the makeMiddleware function.

Sources: middleware/README.md:14-16, middleware/src/middleware.ts:88-90

Middleware Logic Flow

The middleware inspects the User-Agent header and the request path of each incoming request to decide whether it should be proxied to the Rendertron service.

This diagram shows the decision logic within the middleware.

Configuration Parameters

The following options are available for the makeMiddleware function.

Property	Type	Default	Description
proxyUrl	string	Required	The base URL of the running Rendertron service.
userAgentPattern	RegExp	A pattern matching common bots (Googlebot, Bingbot, Slackbot, etc.).	A regular expression to match against the User-Agent header.
excludeUrlPattern	RegExp	A pattern matching common static file extensions (.js, .css, etc.).	A regular expression to exclude requests based on their URL path.
injectShadyDom	boolean	false	If true, appends ?wc-inject-shadydom=true to the render URL to force web components polyfills.
timeout	number	11000	Timeout in milliseconds for the request to the Rendertron service. If exceeded, the middleware falls through to the next handler.

Sources: middleware/README.md:23-30, middleware/src/middleware.ts:68-86

Default Patterns

The middleware comes with predefined regular expression patterns for matching bot user agents and excluding static file types.

Default Bot User Agents:
Baiduspider, bingbot, Embedly, facebookexternalhit, LinkedInBot, outbrain, pinterest, quora link preview, rogerbot, showyoubot, Slackbot, TelegramBot, Twitterbot, vkShare, W3C_Validator, WhatsApp
Sources: middleware/src/middleware.ts:22-38

Default Excluded File Extensions:
ai, avi, css, dat, dmg, doc, exe, flv, gif, ico, iso, jpeg, jpg, js, less, m4a, m4v, mov, mp3, mp4, mpeg, mpg, pdf, png, ppt, psd, rar, rss, svg, swf, tif, torrent, ttf, txt, wav, wmv, woff, xls, xml, zip
Sources: middleware/src/middleware.ts:43-49

Summary

Configuration is a vital part of deploying and using Rendertron effectively. The config.json file provides server-side control over performance, caching, and rendering defaults. The Express middleware options give developers precise control over which user agents receive server-rendered content, ensuring that bots get fully-rendered pages for SEO and social sharing while regular users receive the standard client-side rendered application.