How to shadow other files in Gatsby

Gatsby is a React-based open source framework for creating websites and apps that is basically a static site generator. Gatsby will produce static HTML files that can be loaded onto a server. Gatsby themes are plugins that include a gatsby-config.js file and add pre-configured functionality, data sourcing, and/or UI code to Gatsby sites.

Shadowing in gatsby themes

Gatsby themes allow “shadowing”, which allows a user to replace any file implemented in the webpack bundle from the src directory. This applies to many React components, JSON files, pages, Typescript files, and other imported files.

Shadowing is commonly used to customize the bio component in gatsby.

Shadowing other files

Shadowing is often used to customize and change the style of any theme. Some themes, including gatsby-theme-blog, install additional plugins – gatsby-theme-blog uses gatsby-plugin-theme-ui with the gatsby-theme-ui-preset.

In order to shadow an index.js file from gatsby-plugin-theme-ui, a user needs to create a file named user-site/src/gatsby-plugin-theme-ui/index.js. The file present in gatsby-theme-ui-preset will automatically be merged with the styling convention in index.js:

// index.js
// introduce some styling features
export default {
  fontSize: 10,
  font-family: sans-serif
  color: Navy 
}
// these style will be automatically applied to index.js

Any styles in shadowed files will automatically get deep-merged with the preset theme. Shadowed styles take precedence.

This results in the following directory tree:

user-site
└── src
    └── gatsby-plugin-theme-ui
        └──index.js