The rules of capo.js
Elements are categorized into 11 groups. Each group has an associated weight to determine the optimal sort order. Elements within the same group are considered equal weight and displayed in the order they’re found in the document.
███████████ 11. Pragma directives
Section titled “ 11. Pragma directives”Pragma directives are the highest weighted elements in capo.js. They tell the browser how to parse or handle the document, so they must be discovered as early as possible to avoid race conditions with other content.
<meta http-equiv>
Section titled “<meta http-equiv>”The http-equiv meta tag is used to set directives equivalent to HTTP headers.
Most HTTP headers are unsupported keywords for the http-equiv attribute, so capo.js only recognizes a few of them:
default-stylex-dns-prefetch-controlaccept-chdelegate-chcontent-security-policyorigin-trialcontent-type
Some keywords like refresh are standardized and widely supported by browsers, but capo.js does not weigh them as highly as other http-equiv directives because it’s not strictly necessary for them to be placed in the top position.
default-style
Section titled “default-style”default-style is an obscure-yet-valid keyword that tells the browser which alternate stylesheet to use as the preferred default.
This declaration should come before any stylesheets that may need to be enabled.
x-dns-prefetch-control
Section titled “x-dns-prefetch-control”x-dns-prefetch-control is a non-standard keyword that tells the browser whether to perform DNS prefetching on the page.
Its only legitimate use is to disable prefetching, so when it’s present, capo.js recommends placing it in the top position before any DNS lookups occur.
accept-ch
Section titled “accept-ch”accept-ch is a non-standard keyword that tells the browser which client hints to send back to the server.
This declaration should be set before any subresource requests are made to the origin, so capo.js recommends placing it in the top position.
delegate-ch
Section titled “delegate-ch”delegate-ch is a non-standard keyword that tells the browser which client hints may be delegated to third party origins.
content-security-policy
Section titled “content-security-policy”content-security-policy is a non-standard keyword that provides the browser with a security policy to use on the page.
To effectively mitigate all possible security risks, this declaration should be set before any resource content, so capo.js recommends placing it in the top position.
Note that the meta tag version of CSP has functional limitations compared to the HTTP header, such as lack of support for the report-to directive.
origin-trial
Section titled “origin-trial”origin-trial is a non-standard keyword that allows developers to test new web platform features on a per-origin basis.
See origin trial validation for more information about how capo.js validates origin trial tokens.
Because origin trials have the potential to influence how the browser behaves, capo.js recommends placing this declaration in the top position.
content-type
Section titled “content-type”content-type is a standard keyword that defines the character encoding for the page.
See <meta charset> for more information about why this declaration should be placed in the top position.
<meta charset>
Section titled “<meta charset>”Every page must declare a character encoding of UTF-8, using either the charset meta tag or the Content-Type HTTP response header. When the meta tag is used, it must be discoverable within the first 1024 bytes of the document.
To avoid encoding issues with user-visible content like the <title> element, capo.js recommends placing this declaration in top position.
<meta name=viewport>
Section titled “<meta name=viewport>”The viewport meta tag is used to control the layout of the page on mobile devices.
To avoid a flash of unstyled content or incorrect sizing on mobile devices, capo.js recommends placing the viewport meta tag in the top position.
<base>
Section titled “<base>”The base element sets the base URL for all relative URLs in the document.
To avoid any broken links for resources loaded early in the document, capo.js recommends placing the <base> element in the top position.
██████████ 10. Title
Section titled “ 10. Title”<title>
Section titled “<title>”capo.js recommends placing the <title> element early in the document to ensure it’s discoverable by the browser as early as possible. This is important for users to see the title in the browser tab or title bar, which serves as a signal that the page is loading.
Additionally, placing the <title> after the <meta charset> ensures that any special characters in the title are rendered correctly.
█████████ 9. Preconnect hints
Section titled “ 9. Preconnect hints”<link rel=preconnect>
Section titled “<link rel=preconnect>”Preconnect hints tell the browser to establish a connection to a domain as early as possible, reducing the latency of future requests to that domain.
To maximize the benefit of preconnecting, capo.js recommends placing these hints early in the document, before any resources from that domain are requested.
████████ 8. Asynchronous scripts
Section titled “ 8. Asynchronous scripts”<script async src>
Section titled “<script async src>”Asynchronous scripts are downloaded in parallel to parsing and executed as soon as they are available.
Because they don’t block parsing, capo.js recommends placing them early in the document to start the download as soon as possible.
███████ 7. Import styles
Section titled “ 7. Import styles”@import
Section titled “@import”The @import rule is used to import style rules from other style sheets.
Because @import rules must precede all other types of rules, capo.js recommends placing them early in the document.
Capo.js scans the content of <style> tags for @import rules. If found, the entire <style> element is given a higher weight to encourage moving it earlier in the document, or ideally, replacing the @import with a <link rel=stylesheet> element.
██████ 6. Synchronous scripts
Section titled “ 6. Synchronous scripts”<script src>
Section titled “<script src>”Synchronous scripts block the parsing of the document until they are downloaded and executed.
Capo.js recommends placing them before synchronous styles. While the script still blocks parsing, modern browsers’ preload scanners will discover and start downloading subsequent stylesheets in parallel. If placed after stylesheets, the script’s execution would be blocked until the stylesheets are fully loaded.
█████ 5. Synchronous styles
Section titled “ 5. Synchronous styles”<link rel=stylesheet>
Section titled “<link rel=stylesheet>”<style>
Section titled “<style>”Synchronous styles are critical for rendering the page.
Capo.js recommends placing them early in the document, but after synchronous scripts (if any), to ensure they are discovered and downloaded as soon as possible.
████ 4. Preload hints
Section titled “ 4. Preload hints”<link rel=preload>
Section titled “<link rel=preload>”<link rel=modulepreload>
Section titled “<link rel=modulepreload>”Preload hints tell the browser to download a resource as soon as possible, as it will be needed soon.
While helpful, they are generally less critical than actual resources (like styles and scripts) that are needed immediately. Capo.js recommends placing them after critical resources, but before deferred scripts and prefetch hints, to ensure these resources start downloading as soon as possible.
███ 3. Deferred scripts
Section titled “ 3. Deferred scripts”<script defer src>
Section titled “<script defer src>”Deferred scripts are downloaded in parallel to parsing but executed only after the document has been fully parsed.
Because they don’t block parsing and execute later, capo.js recommends placing them after critical resources and preload hints, but before prefetch hints.
██ 2. Prefetch and prerender hints
Section titled “ 2. Prefetch and prerender hints”<link rel=prefetch>
Section titled “<link rel=prefetch>”<link rel=dns-prefetch>
Section titled “<link rel=dns-prefetch>”<link rel=prerender>
Section titled “<link rel=prerender>”Prefetch and prerender hints tell the browser to prepare for resources that might be needed for future navigations.
Because they are not needed for the current page, capo.js recommends placing them at the bottom of the <head> to ensure they don’t compete with resources needed for the current page.
While dns-prefetch also deals with connection setup like preconnect, it is placed here because it is a speculative hint for future navigations or low-priority resources, whereas preconnect is for resources needed immediately.
█ 1. Everything else
Section titled “ 1. Everything else”Any other elements found in the <head> that don’t match the above categories are given the lowest weight.
This includes elements like Open Graph tags (<meta property="og:title">), description tags (<meta name="description">), icons (<link rel="icon">), and other elements that don’t affect the loading or rendering of the page. Capo.js recommends placing these at the very bottom of the <head>.