Configuring Chromium Flags

Relevant source files

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

• src/config.ts
• src/renderer.ts
• src/rendertron.ts
• README.md
• middleware/README.md
• src/test/app-test.ts

Rendertron leverages Puppeteer to control a headless Chrome instance for rendering web pages. Configuration of the rendering environment occurs at multiple levels: at the browser launch with command-line flags, at the page level with viewport and script evaluations, and at the service level via a configuration file.

This document outlines the different ways to configure Rendertron's rendering behavior. While some options are exposed via API parameters or configuration files, direct modification of Chromium launch flags requires changes to the source code.

Browser Launch Configuration

The primary configuration for the headless Chrome instance happens when the Rendertron service is initialized. This includes setting fundamental browser arguments that affect all subsequent rendering tasks.

Sources: src/rendertron.ts

Puppeteer Launch Arguments

The Rendertron class launches Puppeteer with a hardcoded set of arguments. The only argument specified by default is --no-sandbox. This is a common requirement for running Chrome in containerized environments like Docker.

// src/rendertron.ts:25-25
const browser = await puppeteer.launch({args: ['--no-sandbox']});

There is no mechanism provided through config.json to add or modify these launch arguments. To use different or additional Chromium flags, you must modify the puppeteer.launch call within the Rendertron.initialize method.

The following diagram illustrates the service initialization flow, culminating in the launch of the Puppeteer-controlled browser.

Page-Level Rendering Configuration

For each incoming render or screenshot request, Rendertron applies specific configurations to the individual Puppeteer page. These settings are controlled via API parameters and affect how a specific URL is rendered.

Sources: src/renderer.ts

Viewport and User Agent

Rendertron can simulate a mobile or desktop device by adjusting the viewport and user agent string. This is controlled by the isMobile boolean parameter in the serialize and screenshot methods, which is triggered by the ?mobile query parameter in the API request URL.

Parameter	Effect
isMobile: true	Sets a mobile user agent and applies isMobile: true to the viewport.
isMobile: false	Uses the default desktop user agent and viewport settings.

The mobile user agent is a constant defined in the Renderer.

// src/renderer.ts:13-14
const MOBILE_USERAGENT =
    'Mozilla/5.0 (Linux; Android 8.0.0; Pixel 2 XL Build/OPD1.170816.004) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.75 Mobile Safari/537.36';

Sources: src/renderer.ts:13-14, 76-80, 172-176, src/rendertron.ts:100, 129

Web Components Polyfill Injection

To ensure proper serialization of web components that rely on Shadow DOM, Rendertron forces the use of Shady DOM and related polyfills. It does this by executing scripts on the page context before the target URL's content is loaded.

The following evaluations are performed for every page, regardless of URL parameters:

// src/renderer.ts:82-84
page.evaluateOnNewDocument('customElements.forcePolyfill = true');
page.evaluateOnNewDocument('ShadyDOM = {force: true}');
page.evaluateOnNewDocument('ShadyCSS = {shimcssproperties: true}');

While the README.md and middleware/README.md mention a wc-inject-shadydom=true query parameter to enable this behavior, the core renderer applies these settings unconditionally for every request. The parameter is likely used by middleware to decide whether to route a request to Rendertron but does not alter the renderer's internal logic.

Sources: src/renderer.ts:82-84, README.md, middleware/README.md

The sequence diagram below shows how a render request is processed and these page-level configurations are applied.

Service-Level Configuration (config.json)

Global settings for the Rendertron service are managed through a config.json file located in the project root. These settings control server behavior, caching, and default rendering dimensions but do not include Chromium launch flags.

Sources: src/config.ts, README.md

The ConfigManager class loads these values at startup, overriding the default settings.

Configuration Options

Property	Type	Default	Description
datastoreCache	boolean	false	Enables caching successful renders in Google Cloud Datastore.
timeout	number	10000	The timeout in milliseconds for a page to load (networkidle0).
port	string	3000	The port for the Rendertron HTTP server. Overridden by process.env.PORT.
width	number	1000	The default viewport width for rendering.
height	number	1000	The default viewport height for rendering.

Sources: src/config.ts:28-35, README.md

Configuration Loading Process

Conclusion

Configuring Rendertron's rendering behavior involves a combination of approaches. The most critical Chromium flag, --no-sandbox, is hardcoded for compatibility with containerized environments, and further customization at this level requires modifying the source code. Page-specific settings like viewport, user-agent, and web component polyfills are handled dynamically per request. Finally, service-wide behaviors such as port, timeout, and caching are managed through the config.json file, providing a clear separation of concerns between browser-level and service-level configuration.