Load Taggor early

Most pages use Taggor for a few components. Some pages are almost all components: a landing page, a pricing page, a form page. There you want the components to show early and the page not to jump when they arrive. This guide has the recipe, what it costs and what we measured.

Why the snippet does not block

The snippet is a script tag with the async attribute. The browser downloads it in parallel and never waits for it to parse the page, so if Taggor is slow, blocked by an ad blocker or down, your page still loads and your fallback shows (Fallback content and slots). Taggor does not offer a render-blocking script: it would turn a Taggor outage into a blank page on your site. The recipe below gets the same effect (nothing half-drawn) with a time limit, so the worst case is your own fallback.

The recipe

1. Put the snippet in <head>, with the preload hints

node taggor.mjs sites snippet --preload

prints the hints and the snippet. In the portal, open the site, the Install tab and tick Load Taggor early. Paste everything in <head> of every page:

<link rel="preconnect" href="https://cdn.taggorcdn.com" crossorigin>
<link rel="preload" as="script" href="https://cdn.taggorcdn.com/s/<site-key>.js">
<link rel="modulepreload" href="https://cdn.taggorcdn.com/rt/<runtime-version>/runtime.js">
<script async src="https://cdn.taggorcdn.com/s/<site-key>.js"></script>

• The loader tells the browser which runtime version your site is served; the command reads it from your site’s own loader, so the hint names the version in force today. After a runtime release, run the command again and paste the new hint; a hint for an old version only wastes a download, it breaks nothing. If the version cannot be read, the command leaves that line out.
• The component bundles are addressed by their content and change with every publish, so they cannot be in a fixed snippet. The loader fetches them as soon as it runs.
• Under a Content-Security-Policy, the hints follow the same script-src as the snippet: list the CDN origin as in Content-Security-Policy. We run the three hints under a policy that lists only that origin for scripts, and the browser reports no violation.

2. Hold the region of the page that depends on Taggor, with a time limit

node taggor.mjs sites snippet --hold 1 (or the Hold the page box in the portal) adds this CSS to the snippet for you, for 1 to 3 seconds and never more; it is off unless you ask. Or write it yourself:

Give the part of the page that is made of components a class, and hold it until its components are defined, for at most one second:

<style>
  @media (scripting: enabled) {
    .taggor-region:has(:not(:defined)) {
      visibility: hidden;
      animation: taggor-reveal 0s linear 1s forwards;
    }
  }
  @keyframes taggor-reveal {
    to {
      visibility: visible;
    }
  }
</style>

<main class="taggor-region">
  <finance-simulator rate="1.4">
    <a href="https://example.com/simulator">Simulate on our site</a>
  </finance-simulator>
</main>

• :not(:defined) matches a component tag until its component is registered, so the region stays invisible while the components load and shows the moment the last one is defined.
• The animation lasts 0 seconds and starts after the limit (here 1s): when it fires, the region shows whatever it holds, which is your fallback. Taggor down, blocked or slow costs the visitor at most that second, and the page is never blank for longer.
• visibility: hidden keeps the region’s place, so nothing moves when it shows. Give each component tag its final size with :not(:defined) as in Fallback content and slots.
• Hold only the regions made of components, never the whole <body>. Text that matters for search and reading stays outside the region, or inside the fallback.
• Keep the limit short. One second is a good start; raise it only when you have seen your components take longer on a real connection, and never above three seconds.
• In a browser without JavaScript the rule does not apply (scripting: enabled), and in a browser that does not know :has the whole rule is ignored: both show the fallback at once.

Do not use the hold on a page that disables animations. The hold ends by a CSS animation, so a rule such as * { animation: none !important } (a reduced-motion reset, a “disable animations” tool or plugin) cancels it, and with Taggor blocked or down the region then stays invisible. Check your page’s CSS first; if it has such a rule, skip the hold and keep the fallback visible.

Do not hide the fallback without the time limit: if the script never arrives, the content stays hidden for good.

3. Load a component later, if it is low on the page

A component far down the page does not need its bundle at the first paint. Tell Taggor to fetch it once the page is idle:

node taggor.mjs attach <component> --loading idle

(or When the page loads this component in the portal, on the site’s component props). eager, the default, imports on load. idle waits for a quiet moment of the page, at most two seconds, and then imports the bundle; the runtime itself still loads at once, so the saving is the component’s own bytes. Keep its fallback in the HTML and reserve its size with :not(:defined) so nothing jumps when it shows. If the wait cannot run, the component simply loads on load. A third value, visible, is not available yet.

What we measured

A test page with two components, the snippet in <head>, Chromium with a throttled network, one cold visit per run and the median of five runs. The time is from the start of the navigation to the first rendered component (the harness serves the bytes uncompressed, about three times what the CDN sends):

Network	No hints	Only preconnect and loader preload	All three hints
Slow 4G (150 ms, 1.6 Mbit/s)	999 ms	998 ms	915 ms (-84 ms)
Fast 4G (100 ms, 9 Mbit/s)	496 ms	496 ms	482 ms (-14 ms)

Most of the gain is the modulepreload of the runtime: it makes the runtime download in parallel with the loader instead of after it. The preconnect and the loader preload add nothing when the snippet is already in <head> (the browser finds the script tag as early as the hint), but they help a page where the snippet sits late in the body. The gain grows as the connection gets slower, which is where an early component matters most.

Check it

• Block the Taggor script in your browser’s developer tools (Network, block request URL) and reload: the region must show your fallback after the limit, with a working link or text.
• Throttle the network to Slow 4G and reload: the components should show without the page moving.
• In the Network panel, the runtime request should start before the loader request finishes. If it does not, or it is a different version from the one the loader fetches, run sites snippet --preload again.