We recently introduced two brand new built-in APIs that Gatsby users have been asking for, the
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:
When should scripts be put in the Gatsby Head API and when should they be loaded by the Gatsby Script API in your pages or components?
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 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
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
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.
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
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.