🛠 This document provides technical details of installing the PageWorkers tag in your website pages. Refer to the PageWorkers Implementation article for basic installation instructions.

Overview

Like any script added to a webpage, the PageWorkers tag is a resource, and if improperly loaded, it can impact the browser’s HTML parsing and rendering process. This guide includes recommendations on installing the PageWorkers tag on your page, including which behaviors to avoid, to get the full benefit of PageWorkers with minimal impact on your pages' perceived load speed.

About the Tag Installation Method

We recommend installing the PageWorkers tag manually in your source code. While you can install the tag with a third-party tag manager (e.g., Google Tag Manager), we don’t recommend this because a tag manager:

Drastically reduces the flexibility in tag insertion.
Will generally safeguard the loading of your page over the speed of executing the script.
Introduces many advanced configurations that may interfere with loading the PageWorkers script (e.g., scripts not loaded because of cookie banners or consent manager platform settings and scripts not loaded for bots).

Inserting the Tag in your HTML Document

The following methods of installing the PageWorkers tag minimize the impact on these DOM events: DOMContentLoaded (DCL), FirstPaint (FP), FirstContentfulPaint (FCP), LargestContentfulPaint (LCP), and OnLoad (L).

Because the PageWorkers tag code is asynchronous (i.e., the tag executes code in chunks, waiting for several external cues before executing the code), its execution time following download will not occupy the browser’s main thread for an extended time. Therefore, it will not risk delaying DOMContentLoaded by a significant margin. The duration of the tag’s main execution that could occur before firing DOMContentLoaded is less than 50ms.

We recommend three installation configuration options depending on your website architecture (e.g., Multiple-Page Application vs. Single-Page Application) and current browser performance:

Speed-Focused Configuration
Content-Focused Configuration
SPA and SRR Frameworks Configuration

💡 Always load the PageWorkers tag via a script that contains the async attribute to guarantee the tag’s loading time will not negatively impact DOMContentLoaded.

Speed-Focused Configuration

This option maximizes the PageWorkers tag script execution speed. Since PageWorkers performs changes on your website that you want users and bots to see as fast as possible, these changes should be applied quickly once your page is loaded. The best way to ensure a rapid download and execution of the PageWorkers tag is to load it in your document’s head.

We recommend this configuration if any of the following are true:

Your website is a Multiple-Page Application (MPA), where a new HTML page loads on each navigation, vs. a Single-Page Application (SPA), where JavaScript renders new HTML on navigation.
Your website's main content (excluding assets, stylesheets, and images) is not heavily dependent on JavaScript resource loading and execution.
Your website’s main content (excluding assets, stylesheets, and images) loads rapidly.

Content-Focused Configuration

This option executes the PageWorkers tag script after other resources. If your website loads many resources critical for your page to load and you are unsatisfied with your page load speeds, you may append the PageWorkers tag script to the HTML document’s body instead of the head. In this configuration, the browser will not prioritize loading the tag over other resources loaded through the head.

We recommend this configuration if any of the following are true:

Your website’s main content (excluding assets, stylesheets, and images) is heavily dependent on JavaScript resource loading and execution.
Your website’s main content (excluding assets, stylesheets, and images) loads slowly.

👉 Because browsers anticipate resources that will be requested by the document at a later stage, this technique may show similar loading performance results as when the PageWorkers tag script is in the document’s head. Unlike loading the script in the head, the script will only be executed after the HTML parsing has reached the script location on the page.

SPA and SSR Frameworks Configuration

This configuration relies on framework tools to dynamically inject the PageWorkers tag script on the client side in your document’s body. SPA and Server-side Rendering (SSR) frameworks rely heavily on JavaScript hydration to display content on the page. These frameworks load an initial HTML page and the critical JavaScript resources are loaded immediately after. The display of the main content depends on the execution of these critical resources.

If PageWorkers is loaded and executed before or at the same time as critical resources, optimizations may be attempted before the relevant content is displayed on the page. Although the PageWorkers tag is designed to handle this by reapplying them as many times as possible, it is preferable to avoid this and only execute the tag when the page is ready to be modified.

For this purpose, SPA/SSR frameworks favor inserting external scripts dynamically on the client side and appending them to the document’s body. This preserves the main DOM events from being impacted by the inserted scripts and allows time for their content to be displayed before executing the external scripts.

Refer to the framework-specific guides to obtain the desired result for the most popular front-end frameworks, as each may have its own method of implementing this behavior.

Configurations to Avoid

We have measured in extreme cases, immediate execution scripts and defer scripts may cause significant delays to the firing of DOM events such as DOMContentLoaded. Since your browser relies on these DOM events to render the page during parsing, we recommend never using either of the following configurations:

Script tag with the defer property.
Script tag with immediate execution (lacking defer or async).

👉 When the script loading the tag is appended dynamically to your page on the client side (e.g., by a front-end framework), it may be acceptable to load it without the async attribute since its insertion is guaranteed to be performed after your DOMContentLoaded has been fired.

However, dynamic insertion will negatively impact the PageWorkers tag load speed since it will load later than your other resources. This method is more commonly used on SPAs, which rely heavily on JavaScript sources being loaded and executed first.

Installing the PageWorkers Tag on SPAs

Modern web frameworks provide a complete development experience for building full-scale web applications that support SSR and client-side JavaScript hydration. These solutions offer speed and flexibility combined with SPA’s smooth and cohesive user experience. Regardless of the framework, the considerations for incorporating the PageWorkers tag are similar, with variations only in the specific code implementation.

⭐️ The Pageworkers tag can be implemented on websites that use these frameworks.

This section outlines the important characteristics common to most modern web frameworks and how they may impact the PageWorkers tag execution. Visit the following pages for detailed tutorials on inserting the PageWorkers tag on these frameworks:

Comparing SSR SPAs and Non-SSR SPAs

Unlike traditional SPAs that rely on JavaScript executed on the client side to render the the HTML entirely (i.e., SPAs that do not support SSR), SSR-enabled SPAs are rigidly structured into predefined pages that can be precompiled on the server side and delivered as HTML documents to be loaded in the browser without any JavaScript execution.

Two main advantages are:

The initial load time of the landing page is much faster.
JavaScript execution is unnecessary to render a page without interaction, which is useful for bots since they may not always execute JavaScript.

When navigating an SSR-enabled SPA in the browser, the browser will not load a new HTML document on each navigation, just like in a regular SPA. Instead, the SSR-enabled SPA handles the navigation using JavaScript (if JavaScript execution is allowed in the context) and preloaded page metadata. Additional JavaScript files may be loaded as needed, but the original HTML document remains the same.

This causes the first important consequences for PageWorkers:

👉 Whether a SPA uses SSR or not, the PageWorkers tag will only be executed when landing on a page on the client side and will not be:

Re-executed on further website navigation.
Executed on the server-side.

Tag Installation

There are two main considerations to address when incorporating the tag in your application’s source code:

Scope
Priority

Tag Scope: Global vs. Local

You can either install the PageWorkers tag at the top level of your application so it will be applied to all its pages, or add it to a specific subset of its pages.

👉 We recommend adding the tag globally at the top level of your application so it is always loaded and executed on all pages.

Tag Loading Priority

As outlined above, you can load the tag with different priorities in your webpage. In the framework-specific articles, we respect the recommendations established here, constrained by each framework's possibilities.

👉 We recommend dynamically loading the PageWorkers tag in the HTML document’s body with SSR frameworks that rely heavily on JS hydration to display page content. This will only load PageWorkers once it has rendered the main components of the page, which avoids conflicts between JS hydration and PageWorkers optimizations.

See also: