Theme Shadowing

As I’ve alluded to a few times in this section, Gatsby themes are particularly compelling not just as extensions of existing Gatsby functionality, but also for their flexibility. As we’ve seen, theme composition permits multiple Gatsby themes to be arbitrarily installed into a single Gatsby site. Theme shadowing, meanwhile, allows end users of Gatsby themes to replace any file in the src directory with their own overriding implementation instead.

In this section, we’ll cover how theme shadowing works and its various forms. In the process, we’ll look at several real-world examples to understand how theme shadowing adds considerable value to the relatively new concept of Gatsby themes.

Gatsby themes allow you to shadow any file that is handled by Webpack for bundling. This means theme users can override not only individual JavaScript or TypeScript files but also JSON and YAML files as well as CSS stylesheets that are imported into the site. For instance, consider a scenario where we have a theme that provides an article component for content articles. Theme shadowing allows us to override that article component with our own desired logic.

To demonstrate this, let’s walk though one of Gatsby’s official themes, gatsby-theme-blog, which is also a wonderful reference for theme developers.

NOTE

Because Gatsby themes are relatively new entrants to the Gatsby developer experience, Gatsby recommends working with more “monolithic” themes before decomposing them into composable themes. For more information about theme composition and shared global layouts, consult the theme composition page in the Gatsby documentation.