Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →

@opensourceframework/critters

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@opensourceframework/critters

Inline critical CSS and lazy-load the rest. Forked from GoogleChromeLabs/critters.

Source

npm

Version: 1.0.0

Version published: 4 months ago

Weekly downloads: 30

Maintainers: 1

Weekly downloads

Created: 4 months ago

Source

@opensourceframework/critters

Inline critical CSS and lazy-load the rest for faster page loads

This is a maintained fork of the original critters package by GoogleChromeLabs.

📢 Why This Fork?

The original critters package was archived by GoogleChromeLabs in October 2024. This fork continues maintenance to ensure the package remains available and up-to-date for the community.

What this fork provides:

🔄 Continued Maintenance: Ongoing updates and bug fixes
🔒 Security Updates: Prompt patches for vulnerabilities
� Modern Tooling: Updated dependencies and build tools
🧪 Test Coverage: Comprehensive test suite
📖 Documentation: Improved and up-to-date documentation

Attribution

This package is a fork of GoogleChromeLabs/critters, originally created by:

Jason Miller (@developit)
Janicklas Ralph (@janicklas)

Installation

npm install @opensourceframework/critters
# or
yarn add @opensourceframework/critters
# or
pnpm add @opensourceframework/critters

Usage

Basic Usage

import Critters from '@opensourceframework/critters';

const critters = new Critters({
  path: '/path/to/public',
  publicPath: '/'
});

const html = `
  <html>
    <head>
      <link rel="stylesheet" href="/style.css">
    </head>
    <body>
      <h1>Hello World!</h1>
    </body>
  </html>
`;

const processedHtml = await critters.process(html);

With Webpack

// webpack.config.js
const Critters = require('@opensourceframework/critters');

module.exports = {
  // ...
  plugins: [
    new Critters({
      // Options
      preload: 'swap',
      pruneSource: false,
      reduceInlineStyles: true
    })
  ]
};

With Next.js

// next.config.js
const Critters = require('@opensourceframework/critters');

module.exports = {
  webpack: (config, { dev }) => {
    if (!dev) {
      config.plugins.push(
        new Critters({
          preload: 'swap'
        })
      );
    }
    return config;
  }
};

Options

Option	Type	Default	Description
`path`	`string`	`process.cwd()`	Base path for resolving stylesheets
`publicPath`	`string`	`''`	Public URL prefix for stylesheets
`external`	`boolean`	`false`	Only inline styles from `additionalStylesheets`
`additionalStylesheets`	`string[]`	`[]`	Additional stylesheets to inline
`preload`	`string`	`'swap'`	Preload strategy: `'swap'`, `'media'`, `'js'`, `'js-lazy'`, `'body'`, or `'none'`
`noscriptFallback`	`boolean`	`true`	Add `<noscript>` fallback for preloaded stylesheets
`inlineThreshold`	`number`	`0`	Inline stylesheets smaller than this size (bytes)
`minimumExternalSize`	`number`	`0`	Minimum size for external stylesheets
`pruneSource`	`boolean`	`false`	Remove inlined rules from external stylesheet
`mergeStylesheets`	`boolean`	`true`	Merge multiple stylesheets into one
`additionalStylesheets`	`string[]`	`[]`	Fetch additional stylesheets not in the HTML
`reduceInlineStyles`	`boolean`	`true`	Reduce inline styles
`loadFonts`	`boolean`	`true`	Preload critical fonts
`logger`	`object`	`null`	Custom logger instance

Preload Strategies

swap (default): Uses <link rel="preload"> to load CSS asynchronously
media: Uses media attribute trick to load CSS asynchronously
js: Uses JavaScript to load CSS asynchronously
js-lazy: Uses JavaScript with requestAnimationFrame for lazy loading
body: Appends stylesheet to body for async loading
none: No preloading, just inlines critical CSS

How It Works

Critters extracts critical CSS by:

Parsing the HTML document
Finding all linked stylesheets
Parsing CSS rules and matching them against DOM elements
Inlining only the CSS rules that apply to elements in the initial HTML
Lazy-loading the remaining CSS using your chosen preload strategy

Special CSS Comments

Control which CSS gets inlined using special comments:

/* critters:exclude */
.always-external { color: red; }

/* critters:include */
.always-inlined { color: blue; }

/* critters:include start */
.included-rule-1 { color: green; }
.included-rule-2 { color: yellow; }
/* critters:include end */

critters:exclude - Never inline these rules
critters:include - Always inline these rules (even if not matched)
critters:include start / critters:include end - Include a block of rules

Migration from `critters`

If you were using the original critters package, migrating is straightforward:

- import Critters from 'critters';
+ import Critters from '@opensourceframework/critters';

- const critters = new Critters(options);
+ const critters = new Critters(options);

The API is fully compatible with the original package. Simply replace the package name in your dependencies and imports.

API Reference

`new Critters(options)`

Creates a new Critters instance.

`critters.process(html)`

Processes HTML and returns the result with inlined critical CSS.

Parameters:
- html (string): The HTML to process
Returns: Promise<string> - The processed HTML

`critters.readFile(filename)`

Reads a stylesheet file. Override this method to customize file reading.

Parameters:
- filename (string): The path to the stylesheet
Returns: string | undefined - The CSS content

Security

This package includes protections against:

Path traversal attacks (stylesheets outside base path)
HTML injection via CSS content
Malicious media query injection
Script injection via stylesheet URLs

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This fork is maintained by the OpenSource Framework Contributors.

Keywords

FAQs

What is @opensourceframework/critters?

Is @opensourceframework/critters popular?

Is @opensourceframework/critters well maintained?

Package last updated on 16 Feb 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@opensourceframework/critters

@opensourceframework/critters

📢 Why This Fork?

What this fork provides:

Attribution

Installation

Usage

Basic Usage

With Webpack

With Next.js

Options

Preload Strategies

How It Works

Special CSS Comments

Migration from `critters`

API Reference

`new Critters(options)`

`critters.process(html)`

`critters.readFile(filename)`

Security

Contributing

License

Links

Keywords

Related posts

@opensourceframework/critters

@opensourceframework/critters

📢 Why This Fork?

What this fork provides:

Attribution

Installation

Usage

Basic Usage

With Webpack

With Next.js

Options

Preload Strategies

How It Works

Special CSS Comments

Migration from critters

API Reference

new Critters(options)

critters.process(html)

critters.readFile(filename)

Security

Contributing

License

Links

Keywords

Related posts

152 Chrome Live Wallpaper Extensions Hid Ad Tracking and Faked Google Search Traffic

Andrew Becherer Joins Socket as Chief Information Security Officer

Migration from `critters`

`new Critters(options)`

`critters.process(html)`

`critters.readFile(filename)`