Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Webpage pre-rendering service. ⚡️

Subscribe to updates I use usus

Statistics on usus

Number of watchers on Github 763
Number of open issues 19
Average time to close an issue 1 day
Main language JavaScript
Average time to merge a PR less than a minute
Open pull requests 1+
Closed pull requests 1+
Last commit over 2 years ago
Repo Created over 2 years ago
Repo Last Updated over 1 year ago
Size 60 KB
Organization / Authorgajus
Latest Releasev1.6.0
Page Updated
Do you use usus? Leave a review!
View open issues (19)
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating usus for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Travis build status Coveralls NPM version Canonical Code Style Twitter Follow

Webpage pre-rendering service.


  • Renders webpage using the Chrome Debugging Protocol (CDP).
  • Extracts CSS used to render the page.
  • Renders HTML with the blocking CSS made asynchronous.
  • Inlines the critical CSS.
  • Preloads CSS and fonts used to render the page using rel=preload.


Static HTML pages with inline CSS load faster and are better indexed than single page applications (SPA). sus pre-renders single page applications into static HTML with the critical CSS inlined.

Removing the blocking CSS and inlining the CSS required to render the page increases the perceived page loading speed. Presumably, improves SEO by reducing the page loading time.

Read Pre-rendering SPA for SEO and improved perceived page loading speed.


Examples of web pages using sus:


Use cases

  • Produce HTML used to render the page. Used to render single page applications (e.g. React and Angular) to produce a static HTML. This can be used as a replacement of Default behaviour.
  • Extract CSS used to render a specific page. Used to capture the critical CSS. Use --extractStyles option.
  • Produce HTML used to render the page with the critical-path CSS inlined and blocking CSS made asynchronous. Use --inlineStyles option.

Node.js API

sus can be used either as a Node.js dependency or as a CLI program.

import {
} from 'usus';

 * @see
const configuration: UserConfigurationType = {}

const css = await render('', configuration);


// Flow type annotations included for user reference only.
// sus does not depend or require use of Flow type.
// Refer to the table below for an alternative form of documentation.

type CookieType = {|
  +name: string,
  +value: string

export type UserDeviceMetricsOverrideType = {
  +deviceScaleFactor?: number,
  +fitWindow?: boolean,
  +height?: number,
  +mobile?: boolean,
  +width?: number

type FormatStylesType = (styles: string) => Promise<string>;

export type UserConfigurationType = {
  +chromePort?: number,
  +cookies?: $ReadOnlyArray<CookieType>,
  +delay?: number,
  +deviceMetricsOverride?: UserDeviceMetricsOverrideType,
  +extractStyles?: boolean,
  +formatStyles?: FormatStylesType,
  +inlineStyles?: boolean,
  +preloadFonts?: boolean,
  +preloadStyles?: boolean

The default behaviour is to return the HTML.

  • Using the --extractStyles option returns the CSS used to render the document.
  • Using the --inlineStyles option returns HTML document with CSS inlined.
Name Type Description Default value
chromePort number Port of an existing Chrome instance. See Controlling the Chrome instance. N/A
cookies Array<{name: string, value: string}> Sets a cookie with the given cookie data. N/A
delay number Defines how many milliseconds to wait after the load event has been fired before capturing the styles used to load the page. This is important if resources appearing on the page are being loaded asynchronously. number
deviceMetricsOverride See deviceMetricsOverride configuration
extractStyles boolean Extracts CSS used to render the page. false
formatStyles (styles: string) => Promise<string> Used to format CSS. Useful with inlineStyles=true option to format the CSS before it is inlined. N/A
inlineStyles boolean Inlines the styles required to render the document. false
preloadFonts boolean Adds rel=preload for all fonts required to render the page. true
preloadStyles boolean Adds rel=preload for all styles removed from <head>. Used with inlineStyles=true. true
url string The URL to render. N/A

deviceMetricsOverride configuration

Name Type Description Default value
deviceScaleFactor number Overriding device scale factor value. 1
fitWindow boolean Whether a view that exceeds the available browser window area should be scaled down to fit. false
height number Overriding width value in pixels (minimum 0, maximum 10000000). 1080
width number Overriding height value in pixels (minimum 0, maximum 10000000). 1920
mobile boolean Whether to emulate mobile device. This includes viewport meta tag, overlay scrollbars, text autosizing and more. false

For more information about the deviceMetricsOverride configuration, refer to Chrome DevTools Protocol Viewer documentation.


Using sus requires to install usus NPM package and Google Chrome browser (refer to Dependencies).


sus depends on Chrome v59+.

For Docker installation instructions, refer to Building Docker container with Chrome.


Using via the command line interface (CLI)

$ npm install usus --global
$ usus --help
# usus <command> --help
$ usus render --help
# Renders static HTML. Equivalent to
$ usus render --url
# Inlines styles required to render the page.
$ usus render --url --inlineStyles true
# Use cookies when loading the page.
$ usus render --url --cookies foo=bar,baz=qux
# Render emulating a mobile device (example is using iPhone 6 parameters).
$ usus render --url --deviceMetricsOverride.deviceScaleFactor 2 --deviceMetricsOverride.fitWindow false --deviceMetricsOverride.height 1334 true --deviceMetricsOverride.width 750

Building Docker container with Chrome

Add the following line to your Dockerfile:

RUN wget -q -O - | apt-key add - \
  && sh -c 'echo "deb stable main" >> /etc/apt/sources.list.d/google.list' \
  && apt-get update -y \
  && apt-get install google-chrome-stable -y

This assumes that you are extending from the base node image.

Controlling the Chrome instance

By default, sus creates a new instance of Chrome for every render operation and destroys it after completion. However, you can start Chrome independent of sus and re-use the same instance for multiple renderings.

import {
} from 'usus';

const chrome = await launchChrome();

await render('', {
  chromePort: chrome.port,
  inlineStyles: true

await render('', {
  chromePort: chrome.port,
  inlineStyles: true

await chrome.kill();

launchChrome is a convenience method to launch Chrome using default sus configuration. If you need granular control over how Chrome is launched, refer to the chrome-launcher program.

Minifying the CSS

Use the formatStyles callback to minify/ format/ optimize/ remove CSS before it is inlined.

In this example, I am using csso minifier.

import {
} from 'usus';
import {
} from 'csso';

await render(url, {
  formatStyles: (styles: string): Promise<string> => {
    return minify(styles).css;
  inlineStyles: true


Export DEBUG=usus variable to get additional debugging information, e.g.

$ export DEBUG=usus*
$ usus --url


sus uses Chrome Debugging Protocol CSS coverage report to generate a stylesheet used to render the document.


The following programs provide equivalent service:


All of these programs are using PhantomJS or JSDom to render the page/ evaluate the scripts.

sus is different because it is using Chrome Debugging Protocol and it leverages the Chrome CSS coverage report to generate a stylesheet used to render the document.

usus open issues Ask a question     (View All Issues)
  • about 2 years Custom page load event.
  • over 2 years Detect if a page responded with a 404 statusCode
  • over 2 years Add a chart illustrating how usus integrates into the web stack
  • over 2 years Pseudo classes missing from extracted CSS?
  • over 2 years What makes styles 'critical'?
  • over 2 years Do not send unsolicited emails
  • over 2 years Separate inlineStyles and inlining of style imports into two separate options
  • over 2 years Multiple viewports, mobile + non-mobile
  • over 2 years Generate CSS/ JS usage report for a list of pages
  • over 2 years Allow to signal that page has completed rendering
  • over 2 years Create a logo
  • over 2 years Find a better way to inline style imports
  • over 2 years Find a better way to inline CSS
usus open pull requests (View All Pulls)
  • Allow overriding chrome flags on launch
usus list of languages used
usus latest release notes
v1.6.0 v1.6.0

1.6.0 (2017-07-14)


  • add ability to preload fonts () (d4865a50, closes #21)
v1.5.0 v1.5.0

1.5.0 (2017-07-13)

Bug Fixes

  • try to fix travis (50f93d34)
  • install Chrome to fix the CI (b727be62)
  • do not re-inline the inline stylesheets () (60ad77aa, closes #19)


  • allow to use an existing Chrome instance () (6c676b78, closes #9)
  • do not inline CSS from alien frames () (aa3811e2, closes #23)
  • preload CSS in the
  • () (9a9f2fe9, closes #20)
  • match all links with rel=stylesheet (2dab6325)
v1.4.7 v1.4.7

1.4.7 (2017-07-13)

Bug Fixes

  • update dependencies; add node v6 support () () (f925dc97, closes #10, #15)
Other projects in JavaScript