Skip to main content

Behind the Scenes

Curious how Gatsby works under the hood? The pages in this section describe how a Gatsby build works from an internal code/architecture point of view. It should be useful for anyone who needs to work on the internals of Gatsby, or for those who are simply curious how it all works, or perhaps you’re a plugin author and need to understand how core works to track down a bug? Come one, come all!

If you’re looking for information on how to use Gatsby to write your own site, or create a plugin, check out the rest of the Gatsby docs. This section is quite low level.

These docs aren’t supposed to be definitive, or tell you everything there is to know. But as you’re exploring the Gatsby codebase, you might find yourself wondering what a concept means, or which part of the codebase implements a particular idea. These docs aim to answer those kinds of questions.

A few more things. These docs are mostly focused on the build lifecycle (gatsby build). Operations specific to the develop lifecycle (gatsby develop) are mostly ignored. Though this may change in the future. Also, they mostly focus on the happy path, rather than getting bogged down in details of error handling.

The graph below shows roughly how all the sub systems of Gatsby fit together and the input/output artifacts at different parts of the build. To find out how different parts work, click on the nodes in the graph, or use the menu on the left.

graphname cluster_legend Legend gatsby Gatsby redux redux namespace cache site/.cache/ public site/public/ siteData site/external data dataSource data sources. e.g file, contentful sourceNodes source nodes dataSource->sourceNodes nodes nodes sourceNodes->nodes nodesTouched touchedNodes sourceNodes->nodesTouched rootNodeMap rootNodeMap sourceNodes->rootNodeMap generateSchema generate schema nodes->generateSchema schema schema (inc resolvers) nodes->schema rootNodeMap->generateSchema pluginResolvers plugin resolvers pluginResolvers->generateSchema generateSchema->schema createPages site.createPages schema->createPages runQueries extract and run queries schema->runQueries componentFiles React components (src/template.js) componentFiles->createPages pages pages createPages->pages components components createPages->components pages->runQueries writePages writePages pages->writePages buildHtml build-html.js pages->buildHtml components->runQueries components->writePages fragments query fragments *.js fragments->runQueries componentsWithQueries components (with queries) runQueries->componentsWithQueries queryResults JSON result /public/static/d/dataPath runQueries->queryResults dataPaths jsonDataPaths runQueries->dataPaths componentChunks component chunks component---src-blog-[hash].js queryResults->componentChunks dataPaths->writePages dataJson data.json writePages->dataJson asyncRequires async-requires.js writePages->asyncRequires syncRequires sync-requires.js writePages->syncRequires pagesJson pages.json writePages->pagesJson productionApp production-app.js dataJson->productionApp staticEntry static-entry.js dataJson->staticEntry asyncRequires->productionApp syncRequires->staticEntry appWebpack configure webpack (`build-javascript`) buildJavascript build-javascript.js appWebpack->buildJavascript productionApp->buildJavascript buildJavascript->componentChunks appChunk app-[hash].js buildJavascript->appChunk webpackStats webpack.stats.json buildJavascript->webpackStats chunkMap chunk-map.json buildJavascript->chunkMap webpackStats->staticEntry chunkMap->staticEntry htmlWebpack configure webpack (`build-html`) htmlWebpack->buildHtml staticEntry->buildHtml pageRenderer page-renderer.js buildHtml->pageRenderer htmlFiles html files (index.html) buildHtml->htmlFiles pageRenderer->buildHtml

Edit this page on GitHub