Mapping chunks to chunk assets

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 aware of only the componentChunkName, not the generated filename that 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 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:

// public/webpack.stats.json
{
  "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 that 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:

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