RFC: Script component

[tyhopp]

Summary

We would like to introduce a new API in Gatsby that aids in loading third-party scripts performantly. The intention is to offer:

• A high-level API that removes the need to reach for lower-level Gatsby browser/SSR APIs for most use cases
• A convenient way to declare various loading strategies on a per-script basis
• A default loading strategy that gives Gatsby users the most performant option out of the box

To be consistent we'll refer to this API as a "script component" from here on out.

You can follow progress on this RFC via its milestone.

Try it out

The Gatsby <Script> component is now in general availability as of gatsby@4.15.0.

See the release notes and reference documentation for usage information.

Notes about the canaries released during development have been removed and can be viewed in older versions of this document in the GitHub web app.

Motivation

Many important services are used by adding script tags to the DOM, and while doing this isn't particularly difficult, doing so without degrading website responsiveness and related search ranking can prove more difficult.

At present, Gatsby users have access to the tools required to solve for performant script loading (e.g. native async/defer attributes, Gatsby browser/SSR callbacks), but still experience pain leveraging these tools to achieve performance goals.

The goal of this feature is to ease this pain by offering a high-level API with performant defaults for third-party script loading.

Basic example

Usage could look something like:

Note - Strategy names, example scripts and interfaces below are for illustration, they may change.

import * as React from 'react';
import { Script, ScriptStrategy } from 'gatsby';

const GTM = `G-XXXXXXXXXX`; // Example Google Analytics 4 identifier

// Example script sources for illustration
const scripts = {
  dayjs: 'https://unpkg.com/browse/dayjs@1.11.0/dayjs.min.js',
  three: 'https://unpkg.com/three@0.139.1/build/three.js',
  marked: 'https://cdn.jsdelivr.net/npm/marked/marked.min.js',
  gtag: `https://www.googletagmanager.com/gtag/js?id=${GTM}`,
};

// Strategy prop is optional, defaults to post-hydrate
function IndexPage() {
  return (
    <main>
      <h1>Script component proof of concept</h1>
      <Script src={scripts.three} strategy={ScriptStrategy.postHydrate} />
      <Script src={scripts.marked} strategy={ScriptStrategy.idle} />
      <Script src={scripts.gtag} strategy={ScriptStrategy.offMainThread} forward={[`gtag`]} debug={true} />
      <Script id="gtag-config" strategy={ScriptStrategy.offMainThread}>
        {`
          // Example configuration of Google Analytics for use in Partytown
          window.dataLayer = window.dataLayer || [];
          window.gtag = function gtag() { window.dataLayer.push(arguments); }
          gtag('js', new Date()); 
          gtag('config', ${GTM}, { send_page_view: false })
        `}
      </Script>
      <Script id="my-unique-id" dangerouslySetInnerHTML={{ __html: `alert('Hello world')` }} />
      <Script id="my-unique-id-2">{`alert('Hello world')`}</Script>
    </main>
  );
}

export default IndexPage;

Detailed design

Conceptually it's useful to think of strategies that can be defined for script loading on initial page visit:

• Before the page is interactive (before hydration)
• After the page is interactive (after hydration)
• After the page becomes idle

Here's a hypothetical scenario illustrating what that would look like:

In addition, an experimental strategy that loads scripts in a web worker via Partytown will be explored. This is not illustrated in the image above.

Proposed in scope

• Ability to select a strategy (e.g. pre-hydrate, post-hydrate, idle, off-main-thread)
• Default to post-hydrate
• Callbacks for load and error (e.g. onLoad, onError)
• Ability to apply other (regular) attributes to the resulting <script> tag in the page
• Inline scripts via dangerouslySetInnerHTML and template literals
• All non-experimental strategies (including idle that would use a newer web api) supported in all browsers Gatsby supports
• Console warning when same script with same strategy is loaded on same page
• Appropriate documentation and examples

Drawbacks

• This increases the surface area of Gatsby's public API to offer behavior that can be achieved already today in user code (albeit with more effort)
• A composable JSX component makes it possible to accidentally load multiple of the same script at any depth of the DOM (although we can do our best to guard and warn against this)

Alternatives

1. React hook (useScript({ ... }))
   This would fit nicely in a hooks-oriented React mindset, but comes with these drawbacks:

   • Inability to conditionally add scripts since we’d conform to the rules of hooks
   • Divorced conceptually from the underlying <script> tag that the browser sees
   • Concept of hooks is largely a React concept, which is less ideal for a framework agnostic Gatsby future
   • Not able to return a component directly, so we’d have to append to the DOM imperatively

2. React component + utility
   This is a combination of the proposed JSX component and hook. This offers more flexibility, but comes with these drawbacks:

   • Double the API surface area to maintain
   • More difficult to understand and explain since there's not one way to do things
   • Risk of premature optimization for unvalidated use cases

3. Named function exports(s)
   Similar to existing Gatsby APIs (getServerData and config) that work this way at the page level, we could offer something like a gatsbyScripts function export that we handle during the build process. This is alternative might be appealing for its page-level abstraction, but comes with these drawbacks:

   • Not composable
   • Not possible to use in Gatsby SSR APIs like a React component would be
   • Perception of more magic since it's further from the original concept of a <script> tag on an HTML page
   • More complex implementation that could widen the surface area for bugs

By comparison, these are the reasons why a JSX component implementation could be preferable:

• It’s most similar to the web standard <script> tag in the way you use it
• It’s the easiest to understand and explain since it’s framed as an extension of the HTML <script> tag
• It has the lowest migration cost for folks already using <script> tags

Rollout

• We will work on a proof of concept with the goal of releasing canaries for you to try and give feedback on
  • A proof of concept is currently underway. This is not a statement of where we’re going so much as it the direction we are exploring at the moment
• Based on feedback we'll improve the feature
• After GA release add new features as follow-ups that were not critical for GA release

How we teach this

We can communicate this generally as an extension of the HTML <script> tag with more options.

We would need to update Gatsby’s existing documentation on third party script loading and add a new page(s) detailing usage.

In addition, we should update existing examples in the Gatsby monorepo if need be and include a new one demonstrating usage.

Questions for you

In addition to your thoughts generally, we would love to get your views specifically on:

• If you think the illustrated strategy names (e.g. pre-hydrate, post-hydrate, idle, experimental-partytown) communicate the behavior effectively or if other names can describe it better (e.g. before-interactive, after-interactive, etc.)
• Whether you think a dedicated API for dependent scripts (e.g. load script B after A loads) is something that should be included as a feature in scope or not
  • This could also be achieved without a dedicated API via the combination of useState, the onLoad callback and conditional rendering
• If you think Gatsby should export a TypeScript enum that can be used to declare strategies (as shown in the example) or not

Thank you and we look forward to your thoughts and feedback!

[byronlanehill]

I really like this idea, having used other React platforms that implement similar APIs has always made for a great user experience, and in most cases I think reduces the barrier to entry for people trying to learn the platform because they just use the component out of the box rather than needed to understand Browser, SSR, and other APIs to achieve the same thing.

One question: Would the "idle" attribute ensure that it loads long enough after the rest of the page that the script loading times wouldn't be factored into auditing tools like lighthouse? After running some tests on a clients gatsby site I found we could gain an extra 20-30 performance points if that were the case, which would be a major boost!

[tyhopp]

Thanks for your thoughts @byronlanehill!

The idle strategy would make use of requestIdleCallback (+ shim for browsers that haven't implemented it), so the load time and audit scores would depend on what else the specific site is doing on the main thread after hydration.

That being said, when we have a canary out for you to try I'd love to see what results you see in your client's site!

[byronlanehill]

Thanks for the clarification @tyhopp !

That would be great! If you want to add me to the list of testers I'd be more than happy!

[tyhopp]

Thanks @byronlanehill! The canary is in good shape and we'd love to have you try it and give feedback if you have the time. @pragmaticpat's comment has the points we're looking for feedback on - #35404 (comment)

[tinglof]

I think this is a great idea because of two reasons:

1. It creates a standard gatsby way of doing these of things, which makes it easier for everyone involved in the community and in larger projects to be on the same page.
2. It makes it easy to do things right and difficult to do things wrong. This shouldn't be underestimated, even though there has been a way of doing this, making it easy to do it right will make a huge different if we look at all gatsby sites overall.

Big thumbs up from me. As for the questions:

"If you think the illustrated strategy names (e.g. pre-hydrate, post-hydrate, idle, experimental-partytown) communicate the behavior effectively or if other names can describe it better (e.g. before-interactive, after-interactive, etc.)"

I personally like the illustrated names better (eg. pre-hydrate etc) because it is easier to relate to the update cycle in gatsby, otherwise before-interactive etc would have to be translated to pre-hydrate when thinking in technical terms. The drawback is of course that people who aren't familiar with hydrate won't understand it out of the box. But maybe that pushes them to learn it.

"Whether you think a dedicated API for dependent scripts (e.g. load script B after A loads) is something that should be included as a feature in scope or not"

I think this is a great idea but I don't think it needs to be part of the first scope. Once it is out and adopted by people, then it can be assessed if it is needed or not.

"If you think Gatsby should export a TypeScript enum that can be used to declare strategies (as shown in the example) or not"

I don't think this is needed, and as far as I've seen I haven't seen this pattern used anywhere else. Just a typescript interface/type with strategy: "pre-hydrate" | "post-hydrate" | "idle" | "experimental-partytown" would be sufficient.

[tyhopp]

Really appreciate your thoughts @tinglof! You're right on the exported enum idea being something new for a public API, other cases we have this are internal as far as I'm aware. Something to think on more as we iterate, interested to see if others share a similar view.

[tyhopp]

@tinglof would you be interested in trying the canary out? We'd love to get your feedback on the topics @pragmaticpat mentioned in #35404 (comment)

[herecydev]

A simple question for "If you think Gatsby should export a TypeScript enum that can be used to declare strategies (as shown in the example) or not"

When would this ever not be the case? Why would there be any appetite for potentially not doing this?

[marko-hologram]

As someone else mentioned, they could type strategy as a string literal:

strategy: "pre-hydrate" | "post-hydrate" | "idle" | "experimental-partytown"

This approach would remove the need to import an enum when using this component, but would still give you type safety. Enum seems unnecessary in this case.

[tyhopp]

Hi @herecydev @marko-hologram, thanks for the feedback! Would you be willing to give the canary a try? #35404 (comment) has the points we're looking for feedback on if you're interested

[tyhopp]

Hi all, I've updated the RFC above with a section ("Try it out") on how to try out the latest canary release! New canary versions will be added to the list in that section as they become available and will note what they include.

As per the feedback from @tinglof, @herecydev and @marko-hologram on the strategy TypeScript interface, both string literals and the enum can be used to define strategies.

[pragmaticpat]

We'd love to hear any feedback you all have about the new script component that @tyhopp released as a canary (see RFC description for installation instruction).

In case you'd like to give feedback, but are unsure what kind of feedback we're looking for, here are some suggested steps to try:

1. Take note of the latest performance score in lighthouse for your current site
2. For your site on Gatsby Cloud, create a separate branch for testing
3. Install the latest canary for the script component following the instructions in the RFC (also note of any limitations listed for the canary in the RFC)
4. Migrate your 3rd party scripts to the new component using the appropriate strategy for each script
5. 🤔 How was the general DX of this component vs. your current solution? (worse, equal, way better)
   • Why?
6. 🤔 How was your experience migrating to this new Script component?
   • Why?
7. Run a build on Gatsby Cloud for the test branch
8. 🤔 How has the lighthouse performance score changed?
9. 🤔 Are you able to observe the expected change in load sequence given the strategies you used in your browser’s developer tools? (in Chrome this is found in the Performance tab of devtools

Thanks again for giving it a try!

[herecydev]

I'll dive into this a bit more; just some initial thoughts:

At present, Gatsby users have access to the tools required to solve for performant script loading (e.g. native async/defer attributes, Gatsby browser/SSR callbacks), but still experience pain leveraging these tools to achieve performance goals.

Is it really that difficult at the moment? You have an SSR api where you can use setHeadComponents and insert the scripts, meta, links, etc there. Thankfully the suggested <Script> api isn't that complicated but it's another divergance from web standards that makes the code less portable and makes understanding Gatsby more difficult.

The example shows that this is done on each page, that requires either:

1. Each page ensuring it renders the correct components
2. Using a layout component and wrapping each page
3. Using setHeadComponents or another gatsby api to inject them

It might be helpful to outline your expectations here. What's optimal? From my experience scripts rarely change between pages, so ideally I would like to do this using option 3

As an aside, is there similar investment being applied to meta and links? These are things that do often change between pages and currently the recommendation is "use react helmet". Which feels unloved and is a another pile of libraries/plugins to get working. Instead it would be great to see something like this. That to me should be much higher priority if you're after improving DX

[pragmaticpat]

@herecydev - clearly you're reading ahead of the class! Indeed we do plan to introduce a head / meta feature to the framework fairly soon.

Have you tried the new Script component yet? Would love to hear your feedback on the ergonomics and corresponding perf gains.

Thanks for sharing your feedback!

[pragmaticpat]

@herecydev #35841 - per your comment above. We'd love your feedback!

[tyhopp]

This feature is available in 4.15 now 🎉

https://www.gatsbyjs.com/docs/reference/release-notes/v4.15/#script-component

[marko-hologram]

@shalawfatah did you maybe try console logging something inside these template literals to see if this code is even being executed?

[marko-hologram]

I see in docs that there is also the possibility to use dangerouslySetInnerHTML, so maybe you can instead test with that. Or try different "strategy" prop value just to eliminate what might be a potential issue.

I haven't used Gatsby's Script component yet, but I've used other implementations such as Next.js' one and I didn't have issues so far.

[shalawfatah]

@marko-hologram I noticed the Script API does not work when used nested <Helmet> component, because I can write JS in the new component and it appears when it's in a regular component. The problem is I want to call JS in the header of the page, not sure how to do that if not inside React Helmet in Gatsby?.

[shalawfatah]

@marko-hologram I noticed the new <Script> does not work when nested under <Helmet> component, which I use to put scripts in the header of the page. However, it works when used normally inside components. The problem is I want to run scripts inside the page header, and not sure how to do that other than using Helmet. Is there any way ?

[shalawfatah]

A suggestion: how about having an option to put the script either in body or head, as of now, it only puts it in the body of the document. However, some of our content creators always look for such scripts in the head of the document. It will be suitable if we have an option for that.