Establishing parent and child relationships

Many nodes have a relationship to a parent node or child node that establishes a dependency between the two. Gatsby’s build process provides several approaches to create these relationships, which isn’t straightforward due to the fact that all nodes are considered top-level objects in the Redux nodes namespace. For this reason, each node’s children field consists of an array of node identifiers, each pointing to a node at the same level in that Redux namespace, as seen in the following example:

{
  `id1`: { type: `File`, children: [`id2`, `id3`], ...other_fields },
  `id2`: { type: `markdownRemark`, ...other_fields },
  `id3`: { type: `postsJson`, ...other_fields }
}

In Gatsby, all children are stored within a single collection having parent references.

Certain child nodes need to have their relationships to their parent explicitly defined. This is most often the case when nodes are transformed from other nodes through onCreateNode implementations, thereby establishing a relationship between the untransformed parent node and the transformed child node (or a previously transformed parent node in the case of consecutive transformations). For instance, transformer plugins often implement onCreateNode to create a child node, as we saw earlier in this book, invoking createParentChildLink in the process. This function call pushes the transformed child node’s identifier to the parent’s children collection and commits it to Redux.

The definition of child nodes as node identifiers within the top level of the Redux nodes namespace also drives what is known as foreign key references, which are used in GraphQL to access child nodes from the standpoint of the parent node. The names of foreign key fields accessing these foreign keys are suffixed with ___NODE. When Gatsby runs the GraphQL queries for pages and components, it adopts that value as an identifier and searches the Redux nodes namespace for the matching node. We’ll come back to this process when we turn to schema generation.

Handling stale nodes

Each time you run the gatsby build command, because Gatsby is fundamentally a static site generator, there is always a nonzero chance that some node in the Redux nodes namespace will no longer be available because it’s been removed from the upstream data source. The Gatsby build lifecycle needs to be aware of this event in order to handle all nodes appropriately.

In addition to the Redux nodes namespace, there is a nodesTouched namespace that catalogues whether a particular node identifier has been touched by Gatsby during the node creation phase. This process occurs whenever nodes are created or when the touchNode function is called in the Gatsby API. Any nodes that haven’t been touched by the end of the node sourcing phase are deleted from the nodes namespace by identifying the delta between the nodesTouched and nodes Redux namespaces (as seen in src/utils/source-nodes.ts).

When you develop a Gatsby site, nodes are considered to be immutable unless those modifications are directly persisted to Gatsby’s Redux implementation through a Gatsby action. If you change a Node object directly without making Redux aware of the change, other areas of the Gatsby framework won’t be aware either. For this reason, always ensure that whenever you implement a Gatsby API such as onCreateNode you call a function such as createNodeField, which will add the updated field to the node’s node.fields object and persist the new state to Redux. This way, later logic in the plugin will execute properly based on this new state of the node in later build stages.

Inferring fields on the created Node object

Fields that are directly created on the node, meaning fields that are provided through source and transformer plugins (e.g., relativePath, size, and accessTime in nodes of type File), are typically queried through the GraphQL API in a query similar to the following:

node {
  relativePath,
  extension,
  size,
  accessTime
}

These fields are created using the inferObjectStructureFromNodes function in src/schema/infer-graphql-type.js. Based on what kind of object the function is dealing with as it encounters new objects, it can encompass one of the following three subcategories of fields provided on the created Node object:

• A field provided through a mapping in gatsby-config.js

• A field having a value provided through a foreign key reference (ending in ___NODE)

• A plain object or value (such as a string) that is passed in

First, for fields provided through mappings in gatsby-config.js, if the object field being sent for GraphQL type generation is configured in a custom manner in the Gatsby configuration file, it requires special handling. For instance, a typical mapping might look like the following, where we’re mapping a linked type, AuthorYaml, to the MarkdownRemark type so that we make the AuthorYaml.name field available in MarkdownRemark as MarkdownRemark.frontmatter.author:

mapping: {
  "MarkdownRemark.frontmatter.author": `AuthorYaml.name`,
}

In this situation, the field generation is handled by the inferFromMapping function in src/schema/infer-graphql-type.js. When invoked, the function finds the type to which the identified field is mapped (AuthorYaml), which is known as the linkedType. If a field to link by (linkedField, in this scenario name) is not provided to the function, it defaults to id.

Then, Gatsby declares a new GraphQL field whose type is AuthorYaml (which is searched for within the existing list of gqlTypes). Thereafter, the GraphQL field resolver will acquire the value for the given node (in this example, the author string that should be mapped into the identified field) and conduct a search through all the nodes until it finds one with a matching type and matching field value (i.e., the correct AuthorYaml.name).

Second, for foreign key references, the suffix ___NODE indicates that the value of the field is an id that represents another node present in the Redux store. In this scenario, the inferFromFieldName function in src/schema/infer-graphql-type.js handles the field inference. In this process, which is quite similar to the field mapping process described previously, Gatsby deletes ___NODE from the field name (converting author___NODE into author, for instance). Then it searches for the linkedNode that the id represents in the Redux store (the exampleValue for author, which is an id). Upon identifying the correct node through this foreign key, Gatsby acquires the type in the gqlTypes list via the internal.type value. In addition, Gatsby will accept a linkedField value that adheres to the format nodeFieldName___NODE___linkedFieldName (e.g., author___NODE___name can be provided instead of id).

Then, Gatsby returns a new GraphQL field sharing the same type as that represented by the foreign key. The GraphQL field resolver sifts through all the available Redux nodes until it encounters one with the same id. If the foreign key value is instead an array of ids, then Gatsby will return a GraphQLUnionType; i.e., a union of all linked types represented in the array.

Third, for plain objects or value fields, the inferGraphQLType function in src/schema/infer-graphql-types.js is the default handler. In this scenario, Gatsby creates a GraphQL field object whose type it infers directly by using typeof in JavaScript. For instance, typeof(value) === 'string' would result in the type GraphQLString. As the graphql-js library handles this automatically for Gatsby, there is no need for additional resolvers.

However, if the value provided is an object or an array requiring introspection, Gatsby uses inferObjectStructureFromNodes to recurse through the structure and create new GraphQL fields. Gatsby also creates custom GraphQL types for File (src/schema/types/type-file.js) and Date (src/schema/types/type-date.js): if the value looks like it could be a filename or a date, then Gatsby will return the correct custom type.

Inferring child and parent fields

In this section, we’ll examine the schema inference Gatsby undertakes in order to define child fields that have a relationship to their parent field. Consider the example of the File type, for which many transformer plugins exist that convert a file’s contents into a format legible to Gatsby’s data layer. When transformer plugins implement onCreateNode for each File node, this implementation produces File child nodes that carry their own type (e.g., markdownRemark or postsJson).

When Gatsby infers the schema for these child fields, it stores the nodes in Redux by identifying them through ids in each parent’s children field. Then, Gatsby stores those child nodes in Redux as full nodes in their own right. For instance, a File node having two children will be stored in the Redux nodes namespace as follows:

{
  `id1`: { type: `File`, children: [`id2`, `id3`], ...other_fields },
  `id2`: { type: `markdownRemark`, ...other_fields },
  `id3`: { type: `postsJson`, ...other_fields }
}

Gatsby doesn’t store a distinct collection of each child node type. Instead, it stores in Redux a single collection containing all of the children together. One key advantage of this approach is that Gatsby can create a File.children field in GraphQL that returns all children irrespective of type. However, one important disadvantage is that creating fields such as File.childMarkdownRemark and File.childrenPostsJson becomes a more complex process, since no collection of each child node type is available. Gatsby also offers the ability to query a node for its child or children, depending on whether the parent node references one or multiple children of that type.

In Gatsby, upon defining the parent File gqlType, the createNodeFields API will iterate over each unique type of its children and create their respective fields. For example, given a child type named markdownRemark, of which there is only one child node per parent File, Gatsby will create the field childMarkdownRemark. In order to facilitate queries on File.childMarkdownRemark, we need to write a custom child resolver:

resolve(node, args, context, info)

This resolve function will be invoked whenever we are executing queries for each page, like the following query:

query {
  file( relativePath { eq: "blog/my-blog-post.md" } ) {
    childMarkdownRemark { html }
  }
}

In order to resolve the File.childMarkdownRemark field, Gatsby will, for each parent File node it resolves, filter over each of its children until it encounters one of type markdownRemark, which is then returned from the resolver function. Because that children value is a collection of identifiers, Gatsby searches for the node by id in the Redux nodes namespace as well.

Before leaving the resolve function’s logic, because Gatsby may be executing this query from within a page, whenever the node changes we need to ensure that the page is rerendered accordingly. As such, when changes in the node are detected, the resolver function calls the createPageDependency function, passing the node identifier and the page: a field available in the context object within the resolve function’s signature.

Finally, once a node is created and designated a child of some parent node, that fact is noted in the child’s parent field, whose value is the parent’s identifier. Then, the GraphQL resolver for this field searches for that parent by that id in Redux and returns it. In the process, it also adds a page dependency through createPageDependency to record that the page on which the query is present has a dependency on the parent node.

Plural root fields

Plural root fields accept four arguments: filter, sort, skip, and limit. The filter argument permits filtering based on node field values, and sort reorders the result. Meanwhile, the skip and limit arguments offset the result by the number of skip nodes and restrict it to the number of limit items. In GraphQL, plural root fields return a Connection type for the given type name (e.g., BlogArticleConnection for allBlogArticle).

Here is an example of a plural root field query, which retrieves multiple nodes of type blogArticle with two arguments that filter and sort the incoming data:

{
  allBlogArticle(
    filter: { date: { lt: "2020-01-01" } }
    sort: { fields: [date], order: ASC }
  ) {
    nodes {
      id
    }
  }
}

Singular root fields

Singular root fields also accept the filter parameter, but the filter is spread directly into arguments rather than as a distinct key. As such, filter parameters are passed to the singular root field directly and return the resulting object directly. If no parameters are passed, a random node of that type, if it exists, is returned. Because this random node is explicitly undefined, there is no guarantee of stability of that node across individual builds and rebuilds. If there is no node available to return, null is returned.

Here is an example of a singular root field query, which retrieves a single node of type blogArticle by identifying a field and its desired value:

{
  blogArticle(id: { slug: "graphql-is-the-best" }) {
    id
  }
}

Pagination types

As we saw earlier in this section, when a group of nodes is returned in response to a plural root field query, the type returned is Connection, which represents a common pattern in GraphQL. The term connection refers to an abstraction that operates over paginated resources. When you query a connection in GraphQL, Gatsby returns a subset of the resulting data based on defined skip and limit parameters, but you can also perform additional operations on the collection, such as grouping or distinction, as seen in the last two rows the following table (Table 14-3).

Filter types

For each Node type, a filter input type is created in GraphQL. Gatsby provides prefabricated “operator types” for each scalar (e.g., StringQueryOperatorType) that carry keys as possible operators (such as eq and ne) and values as appropriate values for them. Thereafter, Gatsby inspects each field in the type and runs approximately the following algorithm:

• If the field is a scalar:

  • Retrieve a corresponding operator type for that scalar.

  • Replace the field with that operator type.

• If the field is not a scalar:

  • Recurse through the nested type’s fields and then assign the resulting input object type to the field.

Here’s an example of the resulting types for a given Node type:

input StringQueryOperatorInput {
  eq: String
  ne: String
  in: [String]
  nin: [String]
  regex: String
  glob: String
}

input BlogFilterInput {
  title: StringQueryOperatorInput
  comments: CommentFilterInput
  # and so forth
}

Sort types

For sort operations, given a field, GraphQL creates an enum of all fields (which accounts for up to three levels of nested fields) for a particular type, such as the following:

enum BlogFieldsEnum {
  id
  title
  date
  parent___id
  # and so forth
}

This field is then combined with another enum containing an order (ASC for ascending or DESC for descending) into a sort input type:

input BlogSortInput {
  fields: [BlogFieldsEnum]
  order: [SortOrderEnum] = [ASC]
}

Query extraction

The first step in the process is query extraction, which involves the extraction and validation of all GraphQL queries found in Gatsby pages, components, and templates. At this point in the build process, Gatsby has finished creating all the nodes in the associated Redux namespace, inferred a schema from those nodes, and completed page creation. Next, it needs to extract and compile every GraphQL query present in your source files. In the Gatsby source code, the entry point to this step in the process is extractQueries in src/query/query-watcher.js, which compiles each GraphQL query by invoking the logic in src/query/query-compiler.js.

The query compiler’s first step is to utilize babylon-traverse, a Babel library, to load every JavaScript file available in the Gatsby site that contains a GraphQL query, yielding an abstract syntax tree (AST; a tree representation of source code) of results that are passed to the relay-compiler library. The query compilation process thus achieves two important goals:

• It lets Gatsby know if there are any malformed or invalid queries, which are immediately reported to the user.

• It constructs a tree of queries and fragments depended on by the queries and outputs an optimized query string containing all the relevant fragments.

Once this step is complete, Gatsby will have access to a map of file paths (namely of site files containing queries) to individual query objects, each of which contains the raw optimized query text from query compilation. Each query object will also house other metadata, such as the component’s path and the relevant page’s jsonName, which allows it to connect the dots between the component and the page on which it will render.

Next, Gatsby executes the handleQuery function in src/query/query-watcher.js. If the query being handled is a StaticQuery, Gatsby invokes the replaceStaticQuery action to store it in the staticQueryComponents namespace, which maps each component’s path to an object containing the raw GraphQL query and other items. In the process, Gatsby also removes the component’s jsonName from the components Redux namespace.

On the other hand, if the query is a non-StaticQuery, Gatsby will update the relevant component’s query in the Redux components namespace by calling the replaceComponentQuery action. The final step, once Gatsby has saved each query under its purview to Redux, is to queue the queries for execution. Because query execution is primarily handled by src/query/page-query-runner.ts, Gatsby invokes queueQueryForPathname while passing the component’s path as a parameter.

Query execution

The second step in the query extraction and execution process is the actual execution of the queries to enable data delivery. In the Gatsby bootstrap, queries are executed by Gatsby invoking the createQueryRunningActivity function in src/query/index.js. The other two files involved in the query execution process are queue.ts and query-runner.ts, both located in the same Gatsby source directory.

The first thing Gatsby needs to do in order to properly execute queries is to select which queries need to be executed in the first place—a stage complicated by the fact that it also needs to support the gatsby develop process. For this reason, it isn’t simply a matter of executing the queries as they were enqueued at the end of the extraction step. The runQueries function is responsible for this logic.

First, all queries are identified that were enqueued after having been extracted by src/query/query-watcher.js. Then, Gatsby proceeds to catalogue those queries that lack node dependencies: namely, queries whose component paths are not listed in componentDataDependencies. During schema generation, each type resolver records dependencies between pages whose queries are being executed and successfully resolved nodes of that type. As such, if a component is listed in the components Redux namespace but is unavailable in componentDataDependencies, the query has not yet been executed and requires execution. This logic is found in findIdsWithoutDataDependencies.

As we know from spinning up a local development server using the gatsby develop command, each time a node is created or updated, the node must be dynamically updated—or, internally speaking, added to the enqueuedDirtyActions collection. As queries are executed, Gatsby searches for all nodes within this collection in order to map them to those pages that depend on them. Pages depending on dirty nodes (nodes that have gone stale and need updating) have queries that must be executed. This third step in the query execution process also concerns dirty connections that depend on a node’s type. If the node is dirty, Gatsby designates all connections of that type dirty as well. This logic is found in popNodeQueries.

Now that Gatsby has an authoritative list of all queries requiring execution at its disposal, it will queue them for actual execution, kicking off the step by invoking the runQueriesForPathnames function. For each individual page or static query, Gatsby creates a new query job, an example of which is shown here:

{
  id: // Page path, or static query hash
  hash: // Only for static queries
  jsonName: // jsonName of static query or page
  query: // Raw query text
  componentPath: // Path to file where query is declared
  isPage: // true if not static query
  context: {
    path: // If staticQuery, is jsonName of component
    // Page object. Not for static queries
    ...page
    // Not for static queries
    ...page.context
  }
}

Each individual query job contains all of the information it needs to execute the query and encode any dependencies between pages and nodes therein. The query job is enqueued in src/query/query-queue.js, which uses the better-queue library to facilitate parallel execution of queries. Because in Gatsby there are dependencies only between pages and nodes, not between queries themselves, parallel query execution is possible. Each time an item surfaces from the queue, Gatsby invokes query-runner.ts to execute the query, which involves the following three parameters passed to the graphql-js library:

1. The Gatsby schema that was inferred during schema generation

2. The raw query text, acquired from the query job’s contents

3. The context, available in the query job, containing the page’s path and other elements for dependencies between pages and nodes

Thereafter, the graphql-js library will parse and execute the top-level query, invoking the resolvers defined during the schema generation process to query over all nodes of that type in the Redux store. Afterwards, the result is passed through the inner portions of the query, upon which each type’s resolver is called. In some cases, these resolver invocations will use custom plugin field resolvers. Because this step may generate artifacts such as manipulated images, the query execution step of the Gatsby bootstrap is often the most time-consuming. Once this step is complete, the query result is returned.

Finally, as queries are removed from the queue and executed, their results are saved to Redux, and by extension the disk, for later consumption. This process includes conversion of the query result to pure JSON and saving it to its associated dataPath (relative to public/static/d), including the jsonName and hash of the result. For static queries, rather than employing the page’s jsonName, Gatsby utilizes the hash of the query. Once this process is complete, Gatsby stores a mapping of the page to the query result in Redux for later retrieval using the json-data-paths reducer in Redux.

The pages.json file

The pages.json file represents a list of Page objects that are generated from the Redux pages namespace, accounting for the componentChunkName, jsonName, path, and matchPath for each respective Page object. These Page objects are ordered such that those pages having a matchPath precede those that lack one, in order to support the work of cache-dir/find-page.js in selecting pages based on regular expressions prior to attempting explicit paths.

Example output for a given Page object appears as follows:

{
  componentChunkName: "component---src-blog-2-js",
  jsonName: "blog-c06",
  path: "/blog",
},
// more pages

The pages.json file is only created when the gatsby develop command is executed; otherwise, during Gatsby builds, data.json is used and includes page information and other important data.

The sync-requires.js file

The sync-requires.js file is a dynamically created JavaScript file that exports individual Gatsby components, generated by iterating over the Redux components namespace. In these exports, the keys represent the componentChunk name (e.g., component---src-blog-3-js), and values represent expressions requiring the component (e.g., require("/home/site/src/blog/3.js")), to yield a result that looks like the following:

exports.components = {
  "component---src--blog-2-js": require("/home/site/src/blog/2.js"),
  // more components
}

This file is employed during the execution of static-entry.js in order to map each component’s componentChunkName to its respective component implementation. Because production-app.js (covered later in this chapter) performs code splitting, it needs to use async-requires.js instead.

The async-requires.js file

Like sync-requires.js, async-requires.js is dynamically created by Gatsby, but its motivation differs in that it is intended to be leveraged for code splitting by Webpack. Instead of utilizing require to include components by path, this file employs the import keyword together with webpackChunkName hints to connect the dots between a given listed componentChunkName and the resulting file. Because components is a function, it can be lazily initialized.

The async-requires.js file also exports a data function importing data.json, the final file covered in this section. The following code snippet illustrates an example of a generated async-requires.js file:

exports.components = {
  "component---src-blog-2-js": () =>
    import(
      "/home/site/src/blog/2.js"
      /* webpackChunkName: "component---src-blog-2-js" */
    ),
  // more components
}

exports.data = () => import("/home/site/.cache/data.json")

While sync-requires.js is leveraged by Gatsby during static page HTML generation, the async-requires.js file is instead used during the JavaScript application bundling process.

The data.json file

The data.json file contains a complete manifest of the pages.json file as well as the Redux jsonDataPaths object that was created at the conclusion of the query execution process. It is lazily imported by async-requires.js, which is leveraged by production-app.js to load the available JSON results for a page. In addition, the data.json file is used during page HTML generation for two purposes:

1. The static-entry.js file creates a Webpack bundle (page-renderer.js) which is used to generate the HTML for a given path and requires data.json to search pages for the associated page.

2. The data.json file is also used to derive the jsonName for a page from an associated Page object in order to construct a resource path for the JSON result by searching for it within data.json.dataPaths[jsonName].

The following example illustrates a sample generation of data.json:

{
  pages: [
    {
      "componentChunkName": "component---src-blog-2-js",
      "jsonName": "blog-2-c06",
      "path": "/blog/2"
    },
    // more pages
 ],

 // jsonName -> dataPath
 dataPaths: {
   "blog-2-c06":"952/path---blog-2-c06-meTS6Okzenz0aDEeI6epU4DPJuE",
   // more pages
 }

Splitting into and naming chunks

During Gatsby’s bootstrap phase that concludes with fully written pages, the .cache/async-requires.js file is output. This file exports a components object that contains a mapping of ComponentChunkNames to functions that are responsible for importing each component’s file on disk. This may look something like the following:

exports.components = {
  "component--src-blog-js": () =>
    import(
      "/home/site/src/blog.js"
      /* webpackChunkName: "component---src-blog-js" */
    ),
  // more components
}

As we saw in the previous section, the entry point to Webpack (production-app.js) needs this async-requires.js file to enable dynamic import of page component files. Webpack will subsequently perform dynamic splitting to generate distinct chunks for each of those imported files. One of the file’s exports also includes a data function that dynamically imports the data.json file, which is also code-split.

Once it has indicated where Webpack should split code, Gatsby can customize the nomenclature of those files on disk. It modifies the filenames by using the chunkFilename configuration in the Webpack configuration’s output section, set by Gatsby in webpack.config.js by default as [name]-[contenthash].js. In this naming, [contenthash] represents a hash of the contents of the chunk that was originally code-split. [name], meanwhile, originates from the webpackChunkName seen in the preceding example.

Mapping chunks to chunk assets

In order to generate the mappings required for client-side navigation and future instantaneous loads, Gatsby needs to create:

• <link> and <script> elements that correspond to the Gatsby runtime chunk

• The relevant page chunk for the given page (e.g., with a content hash, component--src-blog-js-2e49587d85e03a033f58.js)

At this point, however, Gatsby is only aware of the componentChunkName, not the generated filename which it needs to reference in the page’s static HTML.

Webpack provides a mechanism to generate these mappings in the form of a compilation hook (done). Gatsby registers for this compilation hook in order to acquire a stats data structure containing all chunk groups. Each of these chunk groups represents the componentChunkName and includes a list of the chunks on which it depends. Using a custom Webpack plugin of its own known as GatsbyWebpackStatsExtractor, Gatsby writes the chunk data to a file in the public directory named webpack.stats.json. This chunk information looks like the following:

{
  "assetsByChunkName": {
    "app": [
      "webpack-runtime-e402cdceeae5fad2aa61.js",
      "app-2e49587d85e03a033f58.js"
    ],
    "component---src-blog-2-js": [
      "0.f8e7f9e53550f997bc53.css",
      "0-d55d2d6645e11739b63c.js",
      "1.93002d5bafe5ca491b1a.css",
      "1-4c94a37dc2061cb7beb9.js",
      "component---src-blog-2-js-cebc3ae7596cbb5b0951.js"
    ]
  }
}

The webpack.stats.json file maps chunk groups (i.e., componentChunkName items) to the chunk asset names on which they depend. In addition, Gatsby’s custom Webpack configuration also generates a chunk-map.json file which maps each chunk group to the core chunk for the component, yielding a single component chunk for JavaScript and CSS assets within each individual chunk group, like the following:

{
  "app":["/app-2e49587d85e03a033f58.js"],
  "component---src-blog-2-js": [
    "/component---src-blog-2-js-cebc3ae7596cbb5b0951.css",
    "/component---src-blog-2-js-860f9fbc5c3881586b5d.js"
  ]
}

Referencing chunks in current page HTML

These two files, webpack.stats.json and chunk-map.json, are then loaded by static-entry.js in order to search for chunk assets matching individual componentChunkName values during the construction of <link> and <script> elements for the current page and the prefetching of chunks for later navigation. Let’s inspect each of these in turn.

First, after generating the HTML for the currently active page, static-entry.js creates the necessary <link> elements in the head of the current page and <script> elements just before the terminal </body> tag, both of which refer to the JavaScript runtime and client-side JavaScript relevant to that page. The Gatsby runtime bundle, named app, acquires all chunk asset files for pages and components by searching across assetsByChunkName items using componentChunkName. Gatsby then merges these two chunk asset arrays together, and each chunk is referred to in a <link> element as follows:

<link
  as="script"
  rel="preload" 
  key="app-2e49587d85e03a033f58.js"
  href="/app-2e49587d85e03a033f58.js"
/>

The rel attribute instructs the browser to begin downloading this resource at a high priority due to the fact that it is likely to be referenced later in the document. At the end of the HTML body, in the case of JavaScript assets, Gatsby inserts the <script> element referencing the preloaded asset:

<script
  key="app-2e49587d85e03a033f58.js"
  src="app-2e49587d85e03a033f58.js"
  async
/>

In the case of a CSS asset, the CSS is injected directly into the HTML head inline:

<style
  data-href="/1.93002d5bafe5ca491b1a.css"
  dangerouslySetInnerHTML="...contents of public/1.93002d5bafe5ca491b1a.css"
/>

Referencing chunks to be prefetched

The previous section accounts for how chunks handled by Webpack are referenced in the page HTML for the current page. But what about subsequent navigation to other pages, which need to be able to load any required JavaScript or CSS assets instantaneously? When the current page has finished loading, Gatsby’s work isn’t done; it proceeds down the page to find any links that will benefit from prefetching.

When Gatsby’s browser runtime encounters a <link rel="prefetch" href="..." /> element, it begins to download the resource at a low priority, and solely when all resources required for the currently active page are done loading. At this point in the book, we come full circle to one of the first concepts introduced: the <Link /> component. Once the <Link /> component’s componentDidMount callback is called, Gatsby automatically enqueues the destination path into the production-app.js file’s loader for prefetching.

Gatsby is now aware of the target page for each link to be prefetched as well as the componentChunkName and jsonName associated with it, but it still needs to know which chunk group is required for the component. To resolve this, the static-entry.js file requires the chunk-map.json file, which it injects it directly into the CDATA section of the HTML page for the current page under window.___chunkMapping so any production-app.js code can reference it, as follows:

<![
  CDATA[ */
    window.___chunkMapping={
      "app":[
        "/app-2e49587d85e03a033f58.js"
      ],
      "component---src-blog-2-js": [
        "/component---src-blog-2-js-cebc3ae7596cbb5b0951.css",
        "/component---src-blog-2-js-860f9fbc5c3881586b5d.js"
      ]
    }
  */ ]
]>

Thanks to this information, the production-app.js loader can now derive the full component asset path and dynamically generate a <link rel="prefetch" ... /> element in prefetch.js, thereupon injecting it into the DOM for the browser to handle appropriately. This is how Gatsby enables one of its most compelling features: instantaneous navigation between its pages.