Portal is a headless Chrome rendering solution designed to render & serialise web pages for use by agents
This repo is a fork of Rendertron, upgraded to support the latest versions of puppeteer, chrome-stable, and container deployments.
๐ค Puppeteer โข ๐ Typescript โข ๐ข Docker
Portal renders requested pages using Headless Chrome, auto-detecting when your PWA has completed loading and serializes the response back to the original request. To use portal, your application configures middleware to determine whether to proxy a request to portal. Portal is compatible with all client side technologies, including web components.
Demo endpoint
A demo portal service is available at https://portal.stuntdouble.io. It is not designed to be used as a production endpoint. You can use it, but there are no uptime guarantees.
Once you have the service up and running, you'll need to implement the differential serving layer. This checks the user agent to determine whether prerendering is required.
This is a list of middleware available to use with the portal service:
- Express.js middleware
- Firebase functions (Community maintained)
- ASP.net core middleware (Community maintained)
Portal is also compatible with prerender middleware. Note: the user agent lists differ there.
GET /render/<url>
The render
endpoint will render your page and serialize your page. Options are
specified as query parameters:
mobile
defaults tofalse
.?mobile
appended will request the mobile version.
GET /screenshot/<url>
POST /screenshot/<url>
The screenshot
endpoint can be used to verify that your page is rendering correctly.
Both endpoints support the following query parameters:
width
defaults to1000
- specifies viewport width.height
defaults to1000
- specifies viewport height.mobile
defaults tofalse
. Enable by passing?mobile
to request the mobile version of your site.
Additional options are available as a JSON string in the POST
body. See
Puppeteer documentation
for available options. You cannot specify the type
(defaults to jpeg
) and encoding
(defaults to binary
) parameters.
When setting query parameters as part of your URL, ensure they are encoded correctly. In JS,
this would be encodeURIComponent(myURLWithParams)
. For example to specify page=home
:
https://portal.stuntdouble.io/render/http://my.domain/%3Fpage%3Dhome
The service detects when a page has loaded by looking at the page load event, ensuring there are no outstanding network requests and that the page has had ample time to render.
There is a hard limit of 10 seconds for rendering. Ensure you don't hit this budget by ensuring your application is rendered well before the budget expires.
Headless Chrome supports web components but shadow DOM is difficult to serialize effectively. As such, shady DOM (a lightweight shim for Shadow DOM) is required for web components.
If you are using web components v0 (deprecated), you will need to enable Shady DOM to
render correctly. In Polymer 1.x, which uses web components v0, Shady DOM is enabled by default.
If you are using Shadow DOM, override this by setting the query parameter dom=shady
when
directing requests to the portal service.
If you are using web components v1 and either webcomponents-lite.js
or webcomponents-loader.js
,
set the query parameter wc-inject-shadydom=true
when directing requests to the portal
service. This renderer service will force the necessary polyfills to be loaded and enabled.
Status codes from the initial requested URL are preserved. If this is a 200, or 304, you can set the HTTP status returned by the rendering service by adding a meta tag.
<meta name="render:status_code" content="404" />
To install puppeteer and run it locally, first install puppeteer:
npm install -g puppeteer
Clone and install dependencies:
git clone https://github.com/turnout-labs/portal.git
cd portal
npm install
npm run build
With a local instance of Chrome installed, you can start the server locally:
npm run start
The indcluded docker file builds a version with chrome-stable bundled in the install process. Accepts PORT as an env variable to adjust the listening port. See https://render.com/docs/deploy-puppeteer-node/
docker build . -t turnout-labs/portal
When deploying the service, set configuration variables by including a config.json
in the
root. Available configuration options:
datastoreCache
defaultfalse
- set totrue
to enable caching on Google Cloud using datastoretimeout
default10000
- set the timeout used to render the target page.port
default3000
- set the port to use for running and listening the portal service. Note if process.env.PORT is set, it will be used instead.width
default1000
- set the width (resolution) to be used for rendering the page.height
default1000
- set the height (resolution) to be used for rendering the page.
If you're having troubles with getting Headless Chrome to run in your environment, refer to the troubleshooting guide for Puppeteer.