Shadowing Other Files

The gatsby-theme-blog theme incidentally installs the gatsby-plugin-theme-ui plugin, which provides a variety of CSS styles to the theme. This plugin includes a preset, gatsby-theme-ui-preset, which is used by the gatsby-theme-blog theme. To shadow a file from a plugin that a theme depends on, we can use much the same approach as before.

Within the src directory, the directory gatsby-plugin-theme-ui contains shadowed files that will override the installed gatsby-plugin-theme-ui dependency’s files. For instance, to override the index.js file in the installed plugin within our site, we can create a shadow file, index.js, and pass in overriding information. Here’s an example:

// src/gatsby-plugin-theme-ui/index.js
const darkBlue = `#007acc`
// const lightBlue = `#66E0FF`
const blueGray = `#282c35`

const theme = {
  colors: {
    text: blueGray,
    primary: darkBlue,
    heading: blueGray,
  },
}

export default theme

Gatsby will combine these values with those already found in gatsby-theme-ui-preset to produce a synthesized version of the index.js file and style values. Whenever these values conflict with those found in the installed plugin, your shadowed files will take precedence.

Remember that any source file handled by Webpack, regardless of extension, can be shadowed to override the upstream theme. Consider, for example, a situation in which you have a theme (let’s call it gatsby-theme-layout) that provides a CSS stylesheet such as components/layout.css. Gatsby developers can create a new folder within their site (src/gatsby-theme-layout) to provide files that shadow the theme’s CSS:

/* src/gatsby-theme-layout/components/layout.css */
body {
  background-color: rebeccapurple;
}

This would then override the entirety of the CSS stylesheet in the upstream theme with the new shadow CSS stylesheet.

NOTE

Gatsby can intelligently guess what extension the component or file that needs to be imported carries when it comes to JavaScript and TypeScript. For instance, if you import a TypeScript file such as src/components/article.tsx as shown here, Gatsby can infer that article.tsx is the correct component:

import Article from "./article"

This is particularly useful in theme shadowing, because you can write an article.js component that shadows an article.tsx TypeScript component without running into transpilation issues.