Support for the Gatsby Script API was added ingatsby@4.15.0.

Gatsby includes a built-in<Script> component that aids in loading scripts performantly.

It offers a convenient way to declare differentloading strategies, and a default loading strategy that gives Gatsby users strong performance out of the box. It supports bothscripts with sources andinline scripts.

Whether you want to leave the heavy lifting of managing scripts to Gatsby or you want maximum flexibility and control, the Gatsby<Script> component is a great tool for the job.

Using Gatsby Script in your site

Here is an example of how you can import and use the<Script> component in your site’s JSX or TSX source files:

If you have existing scripts, using the Gatsby<Script> component is as simple as importingScript and changing lowercasescript tag names to capitalizedScript tag names in most cases:

By default, the<Script> component will load your script after hydration. For more information on declaring loading strategies, see theStrategies section.

Scripts with sources and inline scripts

There are two types of scripts that you can tell the<Script> component to load:

• Scripts with sources
• Inline scripts

Scripts with sources

Scripts with sources provide asrc property like this:

The<Script> component will use the value ofsrc to deduplicate loading, so if you include two scripts on the same page with the samesrc, only one will load.

If for some reason you need to load two scripts with the same sources on the same page, you can provide an optional, uniqueid property to each and the<Script> component will attempt to load both:

Inline scripts

Inline scripts must include a uniqueid property and can be defined in two ways:

• Via React’s specialdangerouslySetInnerHTML property
• Via a template literal

Here’s a look at both:

Functionally, both of these ways of defining inline scripts are equivalent.

Strategies

You can declare a loading strategy by passing astrategy property. These are the available loading strategies:

• post-hydrate (default) - Loads after the page has hydrated
• idle - Loads after the page has become idle
• off-main-thread (experimental) - Loads off the main thread in a web worker viaPartytown

Here’s how you can define these strategies in the<Script> component:

Additionally, Gatsby exports aScriptStrategy enum that you can use in TSX files if you prefer:

Post hydrate strategy (default)

Thepost-hydrate strategy is thedefault loading strategy and will be used if you do not specificy astrategy attribute.

The advantage of this strategy is that you have the ability to declare that your script should start loadingafterhydration. This is impactful because hydration is what makes your page interactive, and by using regular<script> tags (even withasync ordefer applied), you run the risk of your script being loaded in parallel with the framework JavaScript that hydrates your page.

This can have negative implications for key web vital metrics likeTotal Blocking Time. By leveraging the<Script> component with thepost-hydrate strategy, you ensure that your script avoids interfering with your page reaching an interactive state, resulting in a better experience for your users.

Thepost-hydrate strategy is ideal for cases where you want to make sure a script loads early without impacting your site’s time to interactive.

Idle strategy

Theidle strategy is similar topost-hydrate in that it loads after hydration, with the difference beingidle will tell the browser to load the script when the main thread is free.

This means that if your page is doing other crucial work such as DOM manipulations or other calculations that occupy the main thread, your script will wait until after that work is complete to start loading.

Theidle strategy is ideal for cases where you want to ensure a script loads in a way that does not compete with other work being done on the main thread.

Off main thread strategy (experimental)

Theoff-main-thread strategy, unlikepost-hydrate andidle, loads your script in aweb worker viaPartytown.

This means that the burden of evaluation of your script is no longer the concern of the main thread, freeing it up to take care of other crucial tasks.

Note - Due to Partytown’s status asbeta software, theoff-main-thread strategy is consideredexperimental. It is subject to certainlimitations and may require more configuration than other loading strategies depending on your use case.

Here is an example configuring the<Script> component with theoff-main-thread strategy to loadGoogle Analytics:

Forward collection

Gatsby will collect alloff-main-thread scripts on a page, and automatically merge anyPartytown forwarded events defined via theforward property into a single configuration for each page:

Theforward property is the only Partytown-specific property that is handled by the<Script> component.

Proxy configuration

All URLs provided to the Gatsby<Script> component with theoff-main-thread strategy are proxied by Gatsby to/__third-party-proxy?url=${YOUR_URL}.

The reason for this is many third-party scriptsrequire a proxy to work in Partytown, so Gatsby includes built-in proxy functionality to make this easier.

To keep the proxy secure, you must define the absolute URLs you want proxied in your Gatsby config with thepartytownProxiedURLs key. If you do not do this, the the request will 404.

Here’s how you would do that for the Google Analytics example above:

This works out of the box when running your site viagatsby develop,gatsby serve and Gatsby Cloud.

Hosting on other providers requires support for Gatsby’screateRedirect action to rewrite requests from/__third-party-proxy?url=${YOUR_URL} toYOUR_URL with a 200 status code. You may need to check with your hosting provider to see if this is supported.

Resolving URLs

You can leverage Partytown’svanilla config to handle Partytown-specific behavior in youroff-main-thread scripts. One such option isresolveUrl, which allows you to modify URLs handled by Partytown.

One example of a use case forresolveUrl is when using tag manager scripts such asGoogle Tag Manager. These scripts are challenging to use with Partytown since they containother scripts that makeother requests that may or may not need to be proxied depending on the CORS setting. In this scenario you can useresolveUrl to handle those child script URLs.

Here’s an example usingGoogle Tag Manager to loadGoogle Analytics (Universal Analytics in this case):

Note - This assumes you haveset up Google Tag Manager to use Universal Analytics in the Google Tag Manager web application.

First you load your Google Tag Manager (GTM) script and send an initialization event:

Then you defineresolveUrl in Partytown’s vanilla config to handle the Google Analytics script loaded by Google Tag Manager:

Lastly, you need to add the Google Analytics URL topartytownProxiedURLs so that Gatsby knows the URL is safe to proxy:

At this point both your Google Tag Manager and Google Analytics scripts should load successfully in your site.

Debugging

You can also leverage Partytown’svanilla config to enable debug mode for your off-main-thread scripts:

You may need to adjust your dev tools to the verbose log level in order to see the extra logs in your console.

Limitations

By leveragingPartytown, scripts that use theoff-main-thread strategy must also be aware of thelimitations mentioned in the Partytown documentation. While the strategy can be powerful, it may not be the best solution for all scenarios.

These limitations require upstream changes from Partytown to enable:

• TheonLoad andonError callbacks are not supported. Seediscussion #199 in the Partytown repo.
• Scripts load only on server-side rendering (SSR) navigation (e.g. regular<a> tag navigation), and not on client-side rendering (CSR) navigation (e.g. Gatsby<Link> navigation). Seeissue #74 in the Partytown repo.

In addition, theoff-main-thread strategy cannot be used in thewrapRootElement API since script collection depends on location providers. Use thewrapPageElement API instead.

Usage in Gatsby SSR and Browser APIs

The Gatsby<Script> component can also be used in the followingGatsby SSR andGatsby Browser APIs:

• wrapPageElement
• wrapRootElement

Note - If you use one of these APIs, it is recommended that you implement it both in Gatsby SSRand Gatsby Browser. A common pattern is to define a single function that you import and use in both files.

Here’s an example usingwrapPageElement in both Gatsby SSR and Gatsby Browser without duplicating your code:

onLoad andonError callbacks

Scripts with sources loaded with thepost-hydrate oridle strategies have access to two callbacks:

• onLoad - Called once the script has loaded
• onError - Called if the script failed to load

Note - Inline scripts and scripts using theoff-main-thread strategydo not support theonLoad andonError callbacks.

Here is an example using the callbacks:

Duplicate scripts (scripts with the sameid orsrc attributes) will executeonLoad andonError callbacks despite not being injected into the DOM.

Loading scripts dependently

Access to theonLoad andonError callbacks also enables the ability to load scripts dependently. Here’s an example showing how to load the second script after the first: