Controlling Render Timing (render-event)

Relevant source files

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

• src/renderer.ts
• test-resources/explicit-render-event.html
• CHANGELOG.md
• src/test/app-test.ts
• README.md
• middleware/README.md
• middleware/src/middleware.ts

Rendertron employs a sophisticated mechanism to determine when a page has finished rendering before serializing its content. Initially, this was controlled by an explicit event (render-event), but this has been deprecated in favor of an automatic detection system. This page details both the current automatic mechanism and the legacy explicit flag for historical context.

The current system, introduced in version 2.0.0, relies on Puppeteer's ability to monitor network activity to decide when a page is "complete". This removes the need for developers to manually instrument their pages to signal readiness, creating a more robust and streamlined rendering process. A configurable timeout acts as a safeguard to prevent indefinite rendering hangs.

Sources: CHANGELOG.md:13, README.md:50-52

Current Rendering Control: Automatic Detection

The primary mechanism for determining page load completion is based on network activity. Rendertron uses Puppeteer's networkidle0 wait condition. This condition is met when there are no more than 0 network connections for at least 500ms. This approach effectively waits for the page to load its initial resources and complete any subsequent data fetching triggered by client-side scripts.

Sources: src/renderer.ts:101-103, README.md:50-52

Rendering Flow (Automatic)

This diagram illustrates the current rendering sequence using the networkidle0 strategy.

Rendering Timeout

To prevent requests from hanging indefinitely, a rendering budget is enforced. If the page does not reach the networkidle0 state within a specified timeout, the rendering process is aborted, and the content captured up to that point is returned.

The default timeout is 10,000 milliseconds (10 seconds). This can be configured in the config.json file.

Parameter	Description	Default	Source File
timeout	The timeout in milliseconds for rendering the target page.	10000	config.json

Sources: README.md:55-57, 96-97, src/renderer.ts:102

The Express middleware also has its own timeout for the entire proxy request to the Rendertron service. This should typically be set slightly higher than the Rendertron service timeout.

Parameter	Description	Default	Source File
timeout	Millisecond timeout for the proxy request to Rendertron.	11000	middleware.ts

Sources: middleware/README.md:32, middleware/src/middleware.ts:88

Legacy render-event Mechanism (Deprecated)

Note: This feature was removed in version 2.0.0 and is no longer supported. The information is provided for historical context.

Previous versions of Rendertron allowed a page to explicitly signal when it was ready for serialization by setting a global flag: window.renderComplete = true;. Rendertron would poll for this flag and serialize the page once it was set. This gave developers fine-grained control but required manual instrumentation of the front-end code.

Sources: CHANGELOG.md:13, src/test/app-test.ts:125-129, test-resources/explicit-render-event.html

Example Implementation

A page would include a script to manage this flag, typically setting it to true after all asynchronous operations were complete.

<!-- test-resources/explicit-render-event.html -->
<script>
  window.renderComplete = false;
</script>
<script>
  setTimeout(() => {
    document.body.textContent = 'async loaded';
    window.renderComplete = true;
  }, 5000);
  setTimeout(() => {
    document.body.textContent = 'should not be reached';
  }, 11000);
</script>

This example from a test file shows how window.renderComplete would be set to true after a 5-second delay, signaling that the page is ready.

Sources: test-resources/explicit-render-event.html:15-25

The corresponding test for this feature is now marked as failing, confirming its removal from the codebase.

Sources: src/test/app-test.ts:125-129

Summary

The control of render timing in Rendertron has evolved from a manual, event-driven system to a more robust, automatic mechanism. The current approach leverages Puppeteer's networkidle0 state, which simplifies integration by removing the need for client-side signaling. The configurable timeout provides a crucial safety net, ensuring that the service remains responsive. The legacy render-event system is deprecated and should not be used.

Sources: CHANGELOG.md:13, src/renderer.ts:101-103, README.md:50-57