philipp-winterle/crittr

High performance critical css extraction with a great configuration abilities

crittr

High performance critical css extraction library with a multiple url support. crittr enables you to extract the critical path stylesheet rules of a single or multiple urls with lightning speed. Multiple urls are the unique selling point of this library due to the fact that nearly every website using one css file for multiple sub pages. Now you are able to gather the critical css of all pages in one extracting process. And this blazing fast even with rich internet applications! 💪

Feature Facts

• Amazing speed
• Designed to be used by power users as a nodejs module (no useless browser usage)
• 💥 Only library which is able to extract summarized critical css from multiple urls which has a common use case -> Most of the websites using one css file for multiple subpages 💥 🤘
• When using multiple urls a max concurrency of extraction is adjustable. For machines with less power
• Ongoing maintenance because of being used in enterprise environment
• Returns not only the critical css. Also returns the remaining css of your given file. You don't need to include the full css on your page or reduce the css on your own ❤️

Performance

If you use many urls to check against a single css file it will slow down the process. Anyway this is the scenario where crittr can shine. The only thing you need to take care of is the power of the machine you're running crittr on.

Comparison

There are some other libraries out there dealing with the topic of extracting the critical css. Crittr has it's own approach of dealing with this topic. Many features allow users to forget about using any other libraries because crittr already deal with the most things which are important for extracting critical css.

Getting Started

Requirements

• minimum nodejs > 12 | recommended nodejs 16+
• async/await
• Promises
• puppeteer dependecies on UNIX bases OS (including MacOSX)

Due to some dependencies of crittr you may need to install some additional software. Puppeteer has some special requirements if you are running on an UNIX based operation system. You can read more about this fact here. Including a list of what to install: Puppeteer Troubleshooting

Installation

To use crittr as a module or cli in your nodejs environment just install it with

npm i crittr

Usage

Modul usage

To use crittr as a module just require it and choose your options.

The crittr module has the expects an object as input parameter and returns an array with 2 css strings. The first one is the criticalCss string and the second one is the remaining css without the critical selectors.

// async/await
(async () => {
    const { critical, rest } = await crittr(options);
})();

// Promise
crittr(options).then(({ critical, rest }) => {
    // handle css
});

Basic

const Crittr = require('crittr');

Crittr({
    urls: ['https://github.com/'],
    css: `.header-logo-invertocat {
            margin: -1px 15px -1px -2px;
            color: #fff;
            white-space: nowrap;
        }`,
    device: {
        width: 1920,
        height: 1080,
    },
})
    .then(({ critical, rest }) => {
        console.log(critical);
    })
    .catch(err => {
        console.error(err);
    });

As you can also read in the options section there is the possibility to use a css file as a path instead of a string. If the path provided ends with .css it is treated as a file path.

const Crittr = require('crittr');

Crittr({
    urls: ['https://github.com/'],
    css: './test/data/test.css',
}).then(({ critical, rest }) => {
    console.log(critical);
});

Due to the fact, that crittr is returning a Promise you can also use async/await syntax to handle the result.

(async () => {
    const Crittr = require('crittr');
    try {
        const { critical, rest } = await Crittr({
            urls: ['https://github.com/'],
            css: './test/data/test.css',
        });
    } catch (err) {
        console.error(err);
    }
})();

Basic - Whithout css

You can skip adding CSS. Crittr will collect all styles (external and inline) from the first url in your list as base CSS.

Crittr({
    urls: ['https://github.com'],
    device: {
        width: 1920,
        height: 1080,
    },
})
    .then(({ critical, rest }) => {
        console.log(critical);
    })
    .catch(err => {
        console.error(err);
    });

Advanced - Multiple urls

To use the full power of crittr and get the most of the performance advantage you should pass in multiple urls. As of the fact that the most websites use one css file for multiple pages this is the ultimate way to get the critical css for all of them!

const Crittr = require('crittr');

const urls = ['https://example.com/page1', 'https://example.com/page2', 'https://example.com/about', 'https://example.com/shop'];

Crittr({
    urls: urls,
    css: './example.com/css/main.css',
}).then(({ critical, rest }) => {
    // criticalCss contains all the above the fold css
    // restCss is the rest remaining after excluding the criticalCss.
    // You can start including it directly as a defered css without
    // any need to calculate it on your own
    console.log(critical);
});

You can see the output of the time measurement after every run. So you will be able to check you overall processing time.

▶  Crittr Run Initialized timer...
◼  Crittr Run Timer run for: 2.33s

CLI Usage

The CLI usage is not implemented yet 😱. At the moment there is no need of cli usage, but if you need it just open an issue and I will try to get it done! ❤️

Options

Property	Values	Description
urls	Array	An array containing the urls to check the css against. Has to be at least 1 url.
css	String	Optional. Can be a plain css string or path to a css file or empty. If it is a path it has to end with .css! Otherwise it is not recognized as a path. If not set, the whole website css will be taken.
timeout	Number	Optional. Integer number of milliseconds to wait for a page to navigate to. After timeout is reached the page navigation is aborted. ATTENTION: The critical css of the url timed out is not included. Default: 30000
pageLoadTimeout	Number	Optional. After the page load event is fired the pageLoadTimeout is started. After the amount of milliseconds the ongoing loading of assets or xhr requests is stopped and the extraction continues. Default: 2000
outputRemainingCss	Boolean	Optional. If set to false the result obj will not contain any rest css. Only an empty string will be given. Default: true
browser	Object	Optional. Configuration object of browser. E.g. userAgent, ... See documentation for browser object.
device	Object	Optional. Configuration object of device. E.g. width, height, ... See documentation for device object.
puppeteer	Object	Optional. Configuration object of puppeteer options like an already existing browser instance or a path to a Chrome instead of the used Chromium. See documentation for puppeteer object.
printBrowserConsole	Boolean	Optional. If set to true prints console output of urls to the stdoutput. Defaults: false
dropKeyframes	Boolean	Optional. If set to false keeps keyframes as critical css content. Otherwise they are removed. Default: false
takeScreenshots	Boolean	Optional. If set a screenshot is taken for every url processed. Default: false
screenshotPath	String	Optional. The path the screenshots will be saved to. Default: "." (execution path)
screenshotNameGenerator	(url: string) => Promise	Optional. Function that receives the processed URL as an argument and returns a Promise that resolves with the name to be used for the screenshot. When not provided, the URL's name will be sanitized and used as a filename.
keepSelectors	Array	Optional. Every CSS Selector in this array will be kept as part of the critical css even if they are not part of it. You can use wildcards (%) to capture more rules with one entry. Read more. Default: []
removeSelectors:	Array	Optional. Every CSS Selector in this array will be removed of the critical css even if they are part of it. You can use wildcards (%) to capture more rules with one entry. Read more. Default: []
blockRequests	Array	Optional. Some of the requests made by pages are an

Browser options

Property	Values	Description
userAgent	String	Optional. Can be set to any existing user agent
isCacheEnabled	Boolean	Optional. If set to false the browser will cache the result assets as normal behaviour. Default: true
isJsEnabled:	Boolean	Optional. If set to false the execution of Javascript in the browser page is prevented. Default: true
concurrentTabs	Number	Optional. Sets the maximal allowed concurrent tabs being opened at the same time in the browser. This is a useful option if the system has only low performance and to prevent high load. Default: 10 (Can also be set to "Infinity")

Device options

Property	Values	Description
width	Number	Optional. Browser window width in px. Default: 1200
height	Number	Optional. Browser window height in px. Default: 1080
scaleFactor:	Number	Optional. Scaling factor of page. Only needed for mobile device emulation like iPhone. Default: 1
isMobile	Boolean	Optional. If set to true the device type for checking pages is set to mobile. Default: false
isLandscape	Boolean	Optional. If set to true the device orientation is set to landscape. Default: false
hasTouch	Boolean	Optional. If set to true the device viewing the page is assumed having touch. Default: false

Puppeteer options

Property	Values	Description
browser	Promise	Optional. If you already have an puppeteer browser instance created you can use it with this options to prevent crittr from creating a new one. Just for performance!. Default: null
chromePath	String	Optional. Path to other Chrome or Chromium executable/bin file to use. . Default: Default Chromium shipped with puppeteer
headless:	Boolean	Optional. If set to false the browser will launch with GUI to be visible while processing. Default: true

Wildcards

You are already able to define the selectors to force keep or remove. With wildcards you can define a range of selectors to match against one entry in force selectors. The wildcard symbol is the % character. It can put at the beginning or end of a string. Take care of whitespaces between the selector string and the % as it will count as a character. Let's have a quick example:

const { critical, rest } = await Crittr({
    urls: urls,
    css: css,
    keepSelectors: ['.test %'],
});

This keepSelectors options will match every selector that begins with .test and has no further selectors attached. Means .test.test2wouldn't match because there is a whitespace in there. But it will match .test .test2 .test3. Also this example wouldn't match selectors like this:

.pre .test .test2 {
} /* no match */
.pre.test .test2 {
} /* no match */
.test .test2 {
} /* match */
.test.test2 {
} /* no match */
.test .test2:before {
} /* match */

FAQ 😕

• Why do I need to put my css file in when I only want to extract the critical css? You don't need to but if you don't set your css file as an option you may not receive all vendor prefixes you may expect. This is due testing with only one browser engine which drop other prefixes.
• After including the remaining css aswell my page starts looking different. Why is that? If you progress more than 1 url at the same time crittr can not determinate where a rule has to be positioned in the whole css to not get in conflict with other rules overwriting them. You have to write clean css to prevent such an behaviour. Overwriting rules should always have longer selectors than the rules they are overwriting to raise priority.

Upcoming 🎺

• ⭐ cookie includes
• ⭐ wildcards
• 👍 compress output option
• 🔥 return of the remaining css aswell
• ❔ multi selector partial matches
• 🍵 returning of remaining css aswell (optional)
• 🕑 performance boost for large css

Known Bugs 💩

None yet

Troubleshooting

WSL / Windows Linux Subsystem Support

Some unkown reasons prevent puppeteer to run properly in a WSL environment. If you have any errors please try to use your default OS command shell or equivalent. If the error still exists don't hesitate to create an issue ticket.

Inspiration

⭐ puppeteer ⭐ penthouse ⭐ critical ⭐ criticalCSS

crittr's Issues

Timeout error in both Linux and Lando/Docker environments

Describe the bug
Maybe this is a puppeteer problem. I managed to run puppeteer in this environment (please see the script below), but Crittr still shows "TimeoutError: Navigation timeout of 30000 ms exceeded".

To Reproduce
Steps to reproduce the behavior:

1. Create a Lando config file

.lando.yml:

name: crittr
services:
  node:
    type: node
    build_as_root:
      - apt update
      - apt install -y fonts-liberation gconf-service libappindicator1 libasound2 libatk1.0-0 libcairo2 libcups2 libfontconfig1 libgbm-dev libgdk-pixbuf2.0-0 libgtk-3-0 libicu-dev libjpeg-dev libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libpng-dev libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 xdg-utils

tooling:
  npm:
    service: node

2. Create test.js file:

I initialized the puppeteer first to make sure that the browser can run correctly. Browser correctly opens GitHub and makes the screenshot.

const puppeteer = require('puppeteer');
const Crittr = require( "crittr" );

(async () => {
	const browser = await puppeteer.launch({headless: true, args: ['--no-sandbox']});
	const page = await browser.newPage();
	await page.goto('https://github.com/');
	await page.screenshot({ path: 'test.png' });

	try {
		await Crittr({
			puppeteer: {
				browser: browser
			},
			urls: ['https://github.com/'],
			css: `.header-logo-invertocat {
            margin: -1px 15px -1px -2px;
            color: #fff;
            white-space: nowrap;
        }`,
			device: {
				width: 1920,
				height: 1080,
			},
		})
	} catch(err){
		console.error(err);
	}


	await browser.close();
})();

3. Run container:

lando start

4. Create package.json:

{
  "name": "lando-crittr",
  "version": "1.0.0",
  "description": "Node Web Server with Lando & Crittr",
  "license": "MIT",
  "dependencies": {
    "crittr": "^1.4.0",
    "puppeteer": "^13.0.1"
  },
  "scripts": {
    "test": "node ./test.js"
  }
}

5. Install dependencies:
   lando npm install

6. Run script:
   lando npm run test

Expected behavior
Script should generate CSS file.

Current behavior
The script can run puppeteer, and can create screenshots of GitHub - so it means that Chromium works correctly.
But when it comes to Crittr, it shows timeout error: TimeoutError: Navigation timeout of 30000 ms exceeded. Could not get critical ast for url https://github.com/

Screenshots

Environment (please complete the following information):

• Lando 3.6.0
• Node.js v14.18.3

Support Mac OS M1 arm64

Describe the bug
When trying to install this package on a Mac M1 arm64 I get the following error:

The chromium binary is not available for arm64

To Reproduce
Steps to reproduce the behavior (Mac M1):

1. Run npm i crittr

Expected behavior
Package should install

Screenshots

Environment (please complete the following information):

• OS: Mac M1
• Version 11.2

can't generate critical css at all

Describe the bug
I'm not able to generate critical css from a website URL no matter what I tried. I followed all the examples and nothing is generated. The critical variable is always empty and I Only get this message

root@LUCIANO-PC:/mnt/g/Projects/critical# node millionbeautylooks_com.js
/mnt/g/Projects/critical/css/millionbeatylooks_com_critical.css
▶  Crittr Run Initialized timer...
◼  Crittr Run Timer run for: 15.81s

I'm not sure if it has any meaning but the end of the timer is marked with red color while the initialize message is marked with green color.

To Reproduce
Steps to reproduce the behavior:

1. Use this js file

js

const Crittr = require("crittr");
const path = require('path');
const fs = require('fs');


var filename = "millionbeatylooks_com_critical.css";
var filepath = path.resolve("./css/" + filename);
if (!fs.existsSync(path.dirname(filepath))) {
    fs.mkdirSync(path.dirname(filepath));
}

const urls = [
    "https://www.millionbeautylooks.com/",
];

console.log(filepath);

Crittr({
    urls: urls,
    css: ".io{}",
}).then(({critical, rest}) => {
    // criticalCss contains all the above the fold css
    // restCss is the rest remaining after excluding the criticalCss.
    // You can start including it directly as a defered css without
    // any need to calculate it on your own
    console.log(critical);
    fs.writeFile(filepath, critical, {}, function () {
    });
    console.log("done");
});

2. execute node

Package.json

{
  "dependencies": {
    "crittr": "^1.2.6",
    "path": "^0.12.7"
  }
}

Expected behavior
I expected to see in console output the critical css, and the critical css stored in the target css file.

Screenshots

Environment (please complete the following information):

• OS: I tried [WSL Debian 9.6, Native Kali Linux kali-rolling, Native Xubuntu ]

Add an option to remove specific CSS declarations

Is your feature request related to a problem? Please describe.
Not all properties are essential in critical CSS. For example, properties such as cursor, color, or border-radius may not need to be included in the final critical CSS. Therefore, it would be incredibly beneficial to have an option to exclude certain declarations from the final critical CSS, which would reduce the overall size.

Describe the solution you'd like
A potential solution could be to introduce a removeDeclarations option

Describe alternatives you've considered
We could use the postcss-discard plugin for this purpose. It accepts a String, RegExp, or a Function to specify which declarations to exclude.

Original CSS:

.pseudo-selector::before {
    color: silver;
    content: 'pseudo ::before';
}

Crittr:

Crittr({
    removeDeclarations: [/color/]
})

Final CSS:

.pseudo-selector::before {
-    color: silver;
    content: 'pseudo ::before';
}

I am willing to contribute and open a PR if you are interested.

Extract classname

Hi,
Thank you for a wonderful lib,

I wonder if is there a way to extract/return all classname of all Above-the-fold contents?
Also, what is the "returns the remaining css" please? as when i run i only get one single css file.

Sorry for a noob question 😅

Leaving css empty should use site css

Describe the solution you'd like
When Iam not using the css property I would like crittr to use the websites css

Describe alternatives you've considered
Using only the css property makes it more complex for basic users without heavy performance lifting

Fonts inside CSS file have a bad path generated

Description:
So this problem occurs when I have a CSS file with following url for fonts:
@font-face{ .... font-family:eicons;src:url('https://mycdnapi/m:0/a:https://www.mysite.com/wp-content/plugins/elementor/assets/lib/eicons/fonts/eicons.eot?5.14.0 .... )

Critical CSS translates that url() to
https://www.mysite.com/fonts/eicons.woff2?5.14.0

It also occurs with any other font URL in the CSS file.

I run this code for generating critical:
Crittr({ urls: [url], device: { scaleFactor: 2, width: 3050, height: 2000, }, pageLoadTimeout: 5000 }) .then(({critical, rest}) => { fs.writeFileSync(output, critical, 'utf-8'); }) .catch(err => { console.error(err); });

The problem is when the font url is bad, gtmetrix speed test has 302 redirects because of the bad url.
https://jmp.sh/eiSaPh0

Add codestyle presets to the project

Is your feature request related to a problem? Please describe.
No

Describe the solution you'd like
To help reducing noise while pull requests crittr should provide a format preset.

@supports inside of @media throws an Exception

Describe the bug
Using @supports css inside of @media throws an exception.
If u remove the Media Query it works.

To Reproduce

(async () => {
    const Crittr = require("crittr");
    try {
        const { critical, rest } = await Crittr({
            urls: _URLS_,
            css: `
               
            @charset "UTF-8";
            @media (min-width: 576px) {
                @supports (display: grid) {
                    div {
                        display: grid;
                      }
                }
            }
            `
        });

        console.log(critical);
    } catch (err) {
        console.error(err);
    }
})();

►  Crittr Run Initialized timer...
C:\Users\Dirk\Desktop\projekte\trash\above\node_modules\crittr\lib\classes\CssTransformator.class.js:140
internalRule.selectors = internalRule.selectors.filter(
                                                ^

TypeError: Cannot read properties of undefined (reading 'filter')
    at C:\Users\Dirk\Desktop\projekte\trash\above\node_modules\crittr\lib\classes\CssTransformator.class.js:140:49
    at Array.map (<anonymous>)
    at C:\Users\Dirk\Desktop\projekte\trash\above\node_modules\crittr\lib\classes\CssTransformator.class.js:136:26
    at Array.map (<anonymous>)
    at CssTransformator.filterByMap (C:\Users\Dirk\Desktop\projekte\trash\above\node_modules\crittr\lib\classes\CssTransformator.class.js:130:44)
    at C:\Users\Dirk\Desktop\projekte\trash\above\node_modules\crittr\lib\classes\Crittr.class.js:747:71
    at processTicksAndRejections (node:internal/process/task_queues:96:5)

Screenshots

Environment (please complete the following information):

• Windows

Additional context
I cant remove the @media @supports becouse it comes out of a vendor ( http://fancybox.net/ ) repository.

CSS files which are on CDN are not processed

Describe the bug
I was testing on same site url and same page of the site.
When the CSS files were ON the CDN generated critical had 8kB, while the CSS files were OFF the CDN the generated critical had 52kB.
Also the Crittr run time while files are ON the CDN: 8.8s, Crittr run time while the files are OFF the CDN: 15.7s - runned via terminal, all the same parameters.

The site screenshot from crittr in both cases is completely normal, which means the CSS files ARE loading correctly.
The generated critical 8kB CSS breaks the site until other CSS is lazy loaded

To Reproduce

1. Put ALL CSS files on the CDN
2. Generate critical via terminal
   node /var/www/critical/crittr.js --url="https://whatever.com"
3. Produced CSS file is far less than when CSS files are OFF the CDN.

Expected behavior
It should be more or less identical +/- 10% size due that CDN changes relative paths to absolute.

Screenshots
https://jmp.sh/cWGJaHp
https://jmp.sh/rhgEri7

Allow internal HTML files to be processed

Is your feature request related to a problem? Please describe.

I wan't to be able to use internal HTML files, instead of URLs. This feature would be good to have, if the URL is behind a password or similar.

Describe the solution you'd like

I wan't to be able to pass in a internal URL in the urls field.

const urls = [
  './crittr/index.html',
  'https://example.com/about',
];

Instances of puppetter not getting closed/killed

Description:
Really simple, if you run many site urls through crittr within a span of few seconds you will get a bunch of puppetter processes open as they don't close.

https://jumpshare.com/v/017bMHfJYHkz1OBqCkmd

** How to reproduce the issue? **
I'm running 50 site urls per minute (approx) and after few minutes crittr processes keep hanging and clog up the server.

Expected behavior
Processes should die when the script ends

Screenshots
https://jumpshare.com/v/017bMHfJYHkz1OBqCkmd

Crittr should terminate command line process when it fails

Is your feature request related to a problem? Please describe.
I'm using crittr to generate critical css for deployment. The deployment process follows these steps:

• grunt _partial_dev_local_before_critical --env="$env" --compress_js=true
  

• node ./crittr.js # its the Critrr running
  

• grunt _partial_dev_local_after_critical_for_deploy
  

The problem:

Sometimes Crittr fails to generate critical css and the deployment continues.
In this case I would like to make sure that the deployment will fail if the critical css is not properly generated.

Describe the solution you'd like

I would like to have an option to make Crittr terminate command line process if it fails.

Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]:

Describe the bug
I run crittR via gulp and minimal settings on windows and I received the following error:

[19:48:34] Starting 'crittrs'... ▶ Crittr Run Initialized timer... [19:48:34] Finished 'crittrs' after 3.06 ms Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file, data, and node are supported by the default ESM loader. On Windows, absolute paths must be valid file:// URLs. Received protocol 'd:' at throwIfUnsupportedURLScheme (node:internal/modules/esm/load:239:11) at defaultLoad (node:internal/modules/esm/load:120:3) at ModuleLoader.load (node:internal/modules/esm/loader:554:13) at ModuleLoader.moduleProvider (node:internal/modules/esm/loader:435:56) at new ModuleJob (node:internal/modules/esm/module_job:76:27) at #createModuleJob (node:internal/modules/esm/loader:448:17) at ModuleLoader.getJobFromResolveResult (node:internal/modules/esm/loader:260:34) at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:241:17) at process.processTicksAndRejections (node:internal/process/task_queues:95:5) at async ModuleLoader.import (node:internal/modules/esm/loader:473:23) { code: 'ERR_UNSUPPORTED_ESM_URL_SCHEME' }

I tried all major node versions from 16 up to 22 and the error stayed the same.

How I ended here:
I tried to replace penthouse in my gulp workflow. First I had to replace all requires with imports because I got the error that a ES6 module can't be required but has to be imported. Made sense to me so far even though the documentation told me to use require. The rewrite did work for all modules and my other gulp workflows actually work as expected.

To Reproduce
Steps to reproduce the behavior:

1. Create a simple gulp workflow with gulp v4 or v5 (mine is v5),
2. run gulp install
3. set "type": "module" in the package.json file
4. Create a minimal gulpfile with the lines:

import crittr from 'crittr';
// criticalCss
export const crittrs = crittR;
async function crittR() {
    crittr({
        urls: ['https://www.google.com'],
        device: {
            width: 1920,
            height: 1080,
        },
    })
    .then(({criticalCss, rest}) => {
        // use the critical css
        console.log(criticalCss)
    })
    .catch(err => {
        console.error(err);
    });
}

5. run gulp crittrs in the terminal

Environment (please complete the following information):

• Windows 10 latest version
• Version [e.g. 18.04]

Additional context
Add any other context about the problem here.

I don't know if something is wrong with my setup or some dependency is having issues with windows. but I somehow can't figure out what the issue is. Maybe someone can help me her.

Thanks in advance

Prevent @media print in atf css

Describe the bug
Media print queries are included into the atf css. This is not needed as atf has nothing to do with printing.

To Reproduce
Steps to reproduce the behavior:

1. create media print in your css
2. run crittr
3. check atf css

Expected behavior
media print is not included into the atf css