Quick Start: Running Locally

Relevant source files

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

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

Rendertron is a headless Chrome rendering solution built with Puppeteer, designed to render and serialize web pages on the fly. Its primary use case is to serve pre-rendered content to bots and web crawlers that do not execute JavaScript, thereby improving SEO for Progressive Web Apps (PWAs) and other modern web applications. Rendertron runs as a standalone HTTP server, processing requests to render specified URLs.

This guide provides instructions for setting up and running the Rendertron service on a local machine for development and testing purposes. It covers installation, configuration, and basic usage of the local server instance. The service is built as a Koa server using TypeScript.

Sources: README.md, CHANGELOG.md:12-15, package.json

Installation and Setup

Before running the application, you need to clone the repository and install its dependencies. The project requires a Node.js version between 7 and 11.

1. Clone the repository:

   git clone https://github.com/GoogleChrome/rendertron.git
   cd rendertron
   

   Sources: README.md:112-113

2. Install dependencies:

   npm install
   

   This command installs all necessary packages listed in package.json, including Koa, Puppeteer, and TypeScript development tools.
   Sources: README.md:114, package.json:30-58

3. Build the project:
   The source code is written in TypeScript and must be compiled to JavaScript.

   npm run build
   

   This executes the TypeScript compiler (tsc) as defined in the build script.
   Sources: README.md:115, package.json:14

Running the Server

Once the project is built, you can start the local server. A local instance of Chrome is required.

• To start the server for production/manual testing:

  npm run start
  

  This command runs the compiled build/rendertron.js file. The server will initialize and start listening on the configured port (default is 3000).
  Sources: README.md:119-121, package.json:16

• To start the server in development mode with auto-reloading:

  npm run monitor
  

  This uses nodemon to watch for file changes in the src directory and automatically restarts the server, which is useful during development.
  Sources: package.json:19

Server Initialization Flow

The server startup process involves initializing the Koa application, launching a Puppeteer-controlled browser instance, and setting up middleware and API routes.

This diagram illustrates the sequence of operations when the Rendertron server starts.

Sources: src/rendertron.ts:26-70

Configuration

Rendertron can be configured by creating a config.json file in the project's root directory. If this file is not present, the application will use default values. The server will also use the PORT environment variable if it is set.

Sources: README.md:136-138, src/config.ts:15, src/rendertron.ts:23

The following table details the available configuration options:

Option	Type	Default Value	Description
datastoreCache	boolean	false	Set to true to enable caching with Google Cloud Datastore.
timeout	number	10000	Timeout in milliseconds for rendering a target page.
port	string	'3000'	The port for the Rendertron service to listen on.
width	number	1000	The viewport width in pixels for the headless browser.
height	number	1000	The viewport height in pixels for the headless browser.

Sources: src/config.ts:19-25, README.md:139-145

Local API Endpoints

Once running, the local server exposes several endpoints for rendering pages, taking screenshots, and health checks.

| Method | Endpoint | Description - |
| GET | /render/:url(.*) | Renders the given URL and returns the serialized HTML content. Supports a ?mobile query parameter. - |
| GET / POST | /screenshot/:url(.*) | Captures a screenshot of the given URL. GET supports width, height, and mobile query params. POST accepts a JSON body with Puppeteer screenshot options. - |
| GET | /_ah/health | A health check endpoint that returns 'OK' with a 200 status code. - |
| GET | / | Serves the index.html static page, which provides a simple UI for testing the render and screenshot endpoints. - |

Sources: src/rendertron.ts:46-65, README.md:54-73, src/test/app-test.ts:33-36

Render Request Flow

The following diagram shows the sequence of events for a /render request.

This diagram illustrates how a client request is processed through the Koa server to the Renderer, which uses Puppeteer to fetch and process the target URL before returning the final serialized content.

Sources: src/rendertron.ts:86-101, src/renderer.ts:31-131