We recently introduced two brand new built-in APIs that Gatsby users have been asking for, the Script and Head APIs. So exciting! If you haven’t had a chance to try them out on your sites, I highly recommend you do so.

When we were working on the Gatsby Head API, someone asked an interesting question:

Let’s dig into this!

Categorizing script types

To answer this question, we need a way to describe different types of scripts precisely. Thankfully, the HTML specification has done that for us already:

The script element allows authors to include dynamic and data block scripts in their documents.

Interesting, so how do we tell the difference between the two? Well, it’s determined by the <script>‘s type attribute.

If the script’s type attribute is missing, empty or a JavaScript mime type (e.g. application/javascript), it’s a dynamic script.

If the script’s type is anything else (e.g. application/ld+json), it’s a data block script.

Here’s an example:

Where to put your scripts

Now that we’ve established what the two different types of scripts are, let’s talk about where they go in Gatsby’s new Head and Script APIs.

If you’re in a hurry, a general rule of thumb is:

• Dynamic scripts should use the Gatsby Script API in your pages or components
• Data block scripts should use the regular <script> tag in the Gatsby Head

This isn’t always true, but in the majority of cases you encounter it will serve you well.

Here’s how we can use the scripts from the earlier example in the Gatsby Script and Head APIs:

To break down our reasoning further, the Gatsby Script API is primarily concerned with loading dynamic scripts (which are blocking by default) performantly, while the Gatsby Head API is primarily concerned with ensuring the document has the appropriate static metadata for search engines and people to consume.

On a more technical level, the Gatsby Script API is performant because it loads your scripts in the browser runtime after hydration (if you’re using the post-hydrate or idle strategy), so you probably don’t want to use the Script component to load data block scripts since they won’t end up in your static HTML files. A regular <script> tag works just fine in this case, and you don’t take a performance hit since data block scripts are not executed by the browser as dynamic scripts.

Wrapping up

That’s all there is! If you made it this far, then you and I went on a grand adventure to the HTML specification to understand dynamic scripts and data block scripts, used both types of scripts in the new Gatsby Script and Head APIs, and finally dug a little deeper into the reasoning behind it all.

I hope you enjoyed this article as much as I enjoyed writing it! See you next time, and happy scripting.