penthouse

You can install penthouse as a development dependency using yarn or npm.

yarn add --dev penthouse

(or npm install if you are not using yarn)

If you see flashes of unstyled content (FOUC) when using critical CSS, check the following:

1. Dynamic/JS Content: Penthouse runs with JavaScript disabled. Ensure all elements you want styled appear in the initial HTML. If content is injected via JS, use the forceInclude option to keep those styles in the critical CSS.
2. DOM Position vs Viewport: Penthouse does not account for absolute positioning or transform values when determining if an element is in the viewport. If an element is early in the DOM but moved into the viewport via CSS, Penthouse might exclude its styles. Use forceInclude to prevent this.

If you are running on Linux and encounter issues with headless Chrome, you may need to install missing dependencies. A common requirement is libnss3.

sudo apt-get install libnss3

If special characters (like arrows) are not showing correctly, ensure you are using the correct hexadecimal format in your CSS, prepended with a backslash.

Example for the arrow glyph →:

1. Find the hex code: '→'.charCodeAt(0).toString(16) (returns 2192).
2. Use in CSS: content: '\2192';

Penthouse uses the debug module. You can enable verbose logging for all components by setting the DEBUG environment variable.

# Basic verbose logging for all components
env DEBUG="penthouse,penthouse:*" node script.js

Penthouse extracts the critical CSS needed to render the above-the-fold content of a page. It uses Puppeteer and a headless Chromium instance.

Only url and cssString (or css) are required. Note that the HTML found via the url is expected to be styled; Penthouse does not inject styles, it only prunes the provided CSS.

To run many jobs effectively, reuse a single browser instance and run each job in its own browser tab to optimize performance.

penthouse({
  url: 'http://google.com',
  cssString: 'body { color: red }'
})
.then(criticalCss => {
  // use the critical css
  fs.writeFileSync('outfile.css', criticalCss);
})

Penthouse allows fine-grained control over the Puppeteer browser instance used for CSS pruning. Key configuration capabilities include:

• userAgent: Set a custom User-Agent string.
• cookies: Pass an array of cookie objects to be set in the browser.
• customPageHeaders: Set extra HTTP headers for the page requests.
• blockJSRequests: If set to true, Penthouse will disable JavaScript and intercept/abort all .js requests to speed up the process and reduce noise.
• width & height: Define the viewport dimensions used to determine critical CSS.

If you encounter the error PAGE_UNLOADED_DURING_EXECUTION: Critical css generation script could not be executed., it typically means the page navigated away (via window.location, a meta tag refresh, or a redirect) after loading but before Penthouse could finish.

To resolve this:

• Remove redirects or move them to the server-side.
• Disable redirects for the critical CSS generation process (e.g., by using a specific query parameter).

You can capture screenshots to visually verify the critical CSS application. Provide a screenshots object with a basePath to enable this. Penthouse will take two screenshots:

1. before: A screenshot of the page with original styles.
2. after: A screenshot of the page after the generated critical CSS has been inlined.

The file extension is determined by the screenshots.type (e.g., jpeg results in .jpg, otherwise .png).

The main export of penthouse is an asynchronous function used to generate critical-path CSS for a given URL. It accepts an options object and can be used with a callback or as a Promise.

Key features include:

• Support for providing CSS via a string (cssString) or a file path (css).
• Viewport configuration via width and height.
• Custom Puppeteer browser control via puppeteer.getBrowser.
• Control over request blocking (blockJSRequests).
• Inclusion/Exclusion of specific selectors (forceInclude, forceExclude).
• Post-formatting to remove specific CSS properties (propertiesToRemove).

When configuring Penthouse, you can use the allowedResponseCode option to ensure the page loads with the expected HTTP status. This option supports three types of validation:

• Number: The response status must exactly match this number (e.g., 200).
• RegExp: The response status string must match the regular expression.
• Function: A custom predicate function that receives the response object and returns a boolean.