rviscomi/capo.js

Get your <head> in order

Inspired by Harry Roberts' work on ct.css and Vitaly Friedman's Nordic.js 2022 presentation:

Why it matters

How you order elements in the <head> can have an effect on the (perceived) performance of the page.

This script helps you identify which elements are out of order.

How to use it

✨ New: Install the Capo browser extension for Chrome or Firefox ✨

1. Install the extension for Chrome or Firefox
2. Explore the console logs

For applications that add lots of dynamic content to the <head> on the client, it'd be more accurate to look at the server-rendered <head> instead.

Programmatic API (v2)

You can also use capo.js programmatically to analyze HTML <head> elements in Node.js or other JavaScript environments.

Installation

npm install @rviscomi/capo.js

Usage

ES Modules

import { analyzeHead } from '@rviscomi/capo.js';
import { BrowserAdapter } from '@rviscomi/capo.js/adapters';

const head = /* your head element */;
const result = analyzeHead(head, new BrowserAdapter());

CommonJS

const { analyzeHead } = require('@rviscomi/capo.js');
const { BrowserAdapter } = require('@rviscomi/capo.js/adapters');

const head = /* your head element */;
const result = analyzeHead(head, new BrowserAdapter());

Learn more about building your own adapters in the custom adapters docs.

Subpath Exports

Import only what you need for smaller bundle sizes:

// Import just the core analyzer
import { analyzeHead, checkOrdering } from "@rviscomi/capo.js";

// Import just adapters
import { BrowserAdapter } from "@rviscomi/capo.js/adapters";

// Import rules API
import { ElementWeights, getWeight } from "@rviscomi/capo.js/rules";

// Import validation API
import { isValidElement, getValidationWarnings } from "@rviscomi/capo.js/validation";

API Reference

Core Functions

• analyzeHead(head, adapter) - Analyzes a head element and returns detailed results
• analyzeHeadWithOrdering(head, adapter) - Analyzes with ordering violations
• checkOrdering(elements) - Checks for ordering violations in element array
• getWeightCategory(weight) - Gets the category name for a weight value

Rules API

• ElementWeights - Constant object mapping element types to weight values
• getWeight(element, adapter) - Gets the weight for a specific element
• getHeadWeights(head, adapter) - Gets weights for all elements in head

Plus individual detector functions: isMeta(), isTitle(), isPreconnect(), etc.

Validation API

• VALID_HEAD_ELEMENTS - Array of valid head element names
• isValidElement(element, adapter) - Checks if an element is valid in head
• hasValidationWarning(element, adapter) - Checks if element has warnings
• getValidationWarnings(head, adapter) - Gets all validation warnings
• getCustomValidations(element, adapter) - Gets custom validation rules

Adapters

• BrowserAdapter - For working with browser DOM elements
• AdapterInterface - Base interface for custom adapters
• validateAdapter(adapter) - Validates an adapter implementation

Migration from v1.x

See the migration guide for detailed migration guide.

Key changes:

• All analysis functions now require an adapter parameter
• New subpath exports for granular imports
• Enhanced TypeScript support via JSDoc

Browser extension

See the extension docs for detailed usage instructions.

WordPress plugin

Automatically reorganize your WordPress site's <head> tags on the server via output buffering using the official Capo WordPress Plugin.

• ⚡ Zero configuration: Plug and play <head> optimization
• 🔄 Deterministic stable sort: Preserves CSS cascade and script execution order
• 🚀 Full page cache compatibility: Works with WP Super Cache, WP Rocket, LiteSpeed, etc.
• 🩺 Site Health integration: Built-in diagnostics under Tools > Site Health and Admin Toolbar

Read the WordPress plugin documentation for full installation and usage details.

Other

Alternatively, you can use local overrides in DevTools to manually inject the capo.js script into the document so that it runs before anything else, eg the first child of <body>. Harry Roberts also has a nifty video showing how to use this feature. This has some drawbacks as well, for example the inline script might be blocked by CSP.

Another idea would be to use something like Cloudflare workers to inject the script into the HTML stream. To work around CSP issues, you can write the worker in such a way that it parses out the correct nonce and adds it to the inline script. (Note: Not tested, but please share examples if you get it working! 😄)

Summary view

The script logs two info groups to the console: the actual order of the <head>, and the optimal order. In this collapsed view, you can see at a glance whether there are any high impact elements out of order.

Each "weight" has a corresponding color, with red being the highest and blue/grey being the lowest. See src/lib/rules.js for the exact mapping.

Here are a few examples.

www.nytimes.com

docs.github.io

web.dev

stackoverflow.com

Detailed view

Expanding the actual or sorted views reveals the detailed view. This includes an itemized list of each <head> element and its weight as well as a reference to the actual or sorted <head> element.

www.nytimes.com

Here you can see a drilled-down view of the end of the <head> for the NYT site, where high impact origin trial meta elements are set too late.