🔷 capo-rules

The most accurate and modern <head> sorting!

[!WARNING] The API is still under development, the goal is to make the library agnostic as possible so that it can be integrated into any framework or build tool.

✨ Features

• 🧩 Comprehensive, accurate, and modern tag detection and sorting rules, adapted from Rick Viscomi's wonderful capo.js library.
• ⚡ Apply group priority and internal priority by tag type within each group.
• 🔒 Stable ordering for equal-priority tags, preserving original relative order when weights are tied.

📦 Installation

You can install capo-rules using npm:

$ npm install capo-rules

Using pnpm:

$ pnpm add capo-rules

Using yarn:

$ yarn add capo-rules

Using bun:

$ bun add capo-rules

⚡ Usage

capo-rules currently exposes a single function:

import { capo } from 'capo-rules'

const html = `
<!doctype html>
<html lang="en">
  <head>
    <meta name="description" content="A page">
    <script src="/defer.js" defer></script>
    <meta charset="utf-8">
    <title>My page</title>
    <link rel="preconnect" href="https://cdn.example.com">
  </head>
  <body>
    <h1>Hello</h1>
  </body>
</html>
`

const sorted = capo(html)

console.log(sorted)

[!NOTE] Only <head> element tags are reordered; non-element nodes keep their positions, content outside head is preserved, and tags with the same priority keep their original order.

⚙️ How it works?

capo-rules sorts head tags in three stages:

See issue #1 for more details.

🏆 Credits

Many thanks to Rick Viscomi for creating capo.js.

📚 Related Projects

@felixicaza/astro-capo: The most accurate and modern <head> sorting in Astro.

🤝 Contributing

Contributions to this library are welcome! If you have any ideas for improvements or new features, please feel free to open an issue or submit a pull request. I appreciate your help in making capo-rules better for everyone. Please read the CONTRIBUTING.md.

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.