š This document provides technical details of installing the PageWorkers tag on websites built with the Next.js framework.
Overview
Next.js is a popular React-powered framework for creating SPA web apps that support SSR. Before reading this article, read Tech Notes: Installing the PageWorkers Tag to learn best practices for loading the PageWorkers tag on your website.
The latest version of Next.js at the time of this documentation is Next.js 14.2.
There are two methods for installing the PageWorkers tag on Next.js frameworks:
Recommended Installation: Global Scope
š Recommendation Summary:
Insert the tag script at your applicationās top level
_app.tsxfile to be available for the entire website.Use the next/script module
<Script/>component.Use the afterInteractive strategy in the
<Script/>component.
Load the PW tag at the topmost level of your application to load it for your entire website. In a typical Next.js app, this should be in a folder named _app.tsx, as in the following example:
Load it with the Next.js built-in script api: next/script.
Example:
Tag Loading Priority
ā ļø Always use strategy="afterInteractive" recommended by Next.js. This will ensure your core Next application is loaded and rendered before the tag is executed and avoid potential negative impact on DOM events from loading the PageWorkers tag.
Next.js will dynamically append the tagās script to the documentās body when using this strategy, in compliance with our recommendations. This will ensure your core Next.js application is loaded and rendered before the tag is loaded and executed.
š When using afterInteractive, Next.js will inject a <script /> tag in the final HTML document without an async or defer property, seemingly contradictory to our recommendation. This is because Next.js will dynamically insert the tag on the client side. The resources will not be loaded with the other main resources during the initial DOM parsing, and therefore, it does not risk impacting the DOMContentLoaded event.
This is all that is required to load the tag directly into your Next.js application.
š” Your tag will be loaded upon landing on any website page but will not be re-executed on navigation.
Alternate Installation: Local Scope
If you know with absolute certainty the tag should only be loaded on a specific subset of your pages, you may insert it on specific pages only. The example below shows the tag is only loaded on Product pages:
š With the alternate installation, the tag will only be loaded when first landing on a Product page, whether the user lands directly on the page or comes from in-app navigation. However, regardless of the landing source, the tag will only be loaded and executed once and will not be re-executed on subsequent navigation, even on other product pages.
As with the global tag installation, you should respect the Next.js recommendation and use the afterInteractive strategy to load the tag.
Things to Avoid
Do not use the beforeInteractive strategy
Next.js does not recommend using the beforeInteractive strategy for any script except for the most essential, as these scripts will be loaded and executed before the rest of your application is even loaded.
Next.js inserts scripts defined with the beforeInteractive strategy into your documentās head with the defer property. You should avoid this since it may significantly impact the DOMContentLoaded event, as explained in our recommendations.
If you must use beforeInteractive with the next/script Script component, you must add the async property since it will prevail over the defer property when both are present (see <script>: The Script element - HTML: HyperText Markup Language | MDN ).
Do not use the native HTML <script>
Do not inject the script using the native HTML <script> tag directly into your documentās head since it might negatively impact your applicationās performance. For instance, the following is incorrect:
Do not insert <Script /> component in _document if using Next.js < v12.2.2
If your application contains a _document.tsx you should not insert the next/script at this level unless you are sure you are using a version of Next.js greater than v12.2.2:
| 
|