Today on stream I worked through the final steps for implementing Child Theming for Gatsby. The interesting outcomes of this are that
src
directory.In this post I'll be referencing work from the gatsby-theme-examples repo
The way I chose to split up the original gatsby-theme-blog
was into two basic pieces. gatsby-theme-blog-core
would
hold the data structures while gatsby-theme-blog
would
handle the UI layer. Since this isn't a post about child
theming itself but rather Component Shadowing, that's really
all you have to know for now.
The idea behind Component Shadowing is fairly small. If we
have some file in our theme theme/a/b.js
, then we can
replace this component at build time by creating a different
file in our own site at our-site/a/theme/b.js
. This means
that themes can take advantage of Component Shadowing for
replacing brand colors, the way a blog post renders, or
anything else that can be represented as a file.
Until now, Component Shadowing was only enabled for files
placed in src/components
. This choice was made to limit
the blast radius while we evaluated the feature itself. As
it turns out, people start putting everything in
src/components
to take advantage of Shadowing. As a result
we've moved the supported directory up one level to src
.
The impact of this change is that Shadowing is enabled by
default for the entire src/
directory. Since
gastby-theme-blog-core
is a parent of gatsby-theme-blog
we have the following set of files.
src/components/blog-post.js
src/gatsby-theme-blog-core/components/blog-post.js
src/gatsby-theme-blog-core/components/blog-post.js
Remember that the order for how this file gets resolved is
the same order that we use for composition. In our case, it
is [gatsby-theme-blog-core
, gatsby-theme-blog
,
user-site
]. The last entry in the array wins.
gatsby-theme-blog-core
offers a shadowable component that
handles rendering for a blog post page template at
src/components/blog-post.js
. The only thing this component
does is dump the props onto the page inside of a <pre>
tag.
import React from "react";export default props => (<pre style={{ whiteSpace: "pre-wrap" }}>{JSON.stringify(props, null, 2)}</pre>);
gatsby-theme-blog
, being responsible for the UI layer,
shadows this component by using a file at
src/gatsby-theme-blog-core/components/blog-post.js
. This
file includes a React component, set of styles, and a much
nicer rendering of the props we have. Because
gatsby-theme-blog
is included "later", it's version of the
blog-post rendering wins.
Then, when we used gatsby-theme-blog
in our own site, we
decided we wanted the blog post to render differently than
the child theme, so we created a new file in our site at
src/gatsby-theme-blog-core/components/blog-post.js
. This
is a very similar location to when we shadowed the blog post
component in the child theme. Because the user's site is
always included last, the new blog post file wins over both
themes.
Component Shadowing is a powerful way for people who are unfamiliar with GraphQL to get started building out their own sites. A child theme could be a collection of these shadowed components that use any set of technologies without needing to worry about writing new GraphQL queries to get data: The page structure and content is already well-defined.