When I started to build a website using GatsbyJS for the first time, I stumbled upon the terms Gatsby Themes and Gatsby Starters. In case you've ever made a website using Wordpress or other website building systems, the terms themes or starters might sound familiar to you. Often it is pretty clear what themes or starters do. They provide boilerplate, functionality- or style-related, to bootstrap your project. However, in the GatsbyJS ecosystem, these terms both appear side by side, but they have a different meaning. Both can do everything doable in a GatsbyJS project, meaning both could provide:
- initial design and styles
- initial plugins functionality
- initial pages generator and website sections logic
So then, why to differentiate those terms? There are differences, essential differences. Those primarily deal with the future and long-term strategy of your GatsbyJS project.
Gatsby Starters - get started very quickly (and then be on your own)
Coming from a Wordpress or similar website building system, Gatsby Starters most likely is the GatsbyJS feature that might fulfill your imagination of what a Wordpress theme does. Using the GatsbyJS CLI to init a starter project, Gatsby Starters provide an initial project starting point - including styles or functionality - to get started very quickly. But that's it. Mentioning this means pointing out the fact that keeping your Gatsby Starter dependencies and Gatsby Starter updates solely depends on you as a developer. In case you're familiar with the create-react-app React application bootstrapping library, compare Gatsby Starters with an eject action of a create-react-app project.
To summarize, think of Gatsby Starters like:
- you fork a git repository, and you and your code changes make the repository grow and evolve
- you create a
create-react-appapplication, eject it, and elaborate application core updates and further developments on your own
Gatsby Themes - get started comfortable (and in the long term benefit from theme updates)
A Gatsby Theme can do everything a Gatsby Starter can do, but with the long-term benefit of enabling theme updates somewhere in the future of your GatsbyJS project. Compared to Gatsby Starters, this is possible because a Gatsby Theme is attached to your project as a GatsbyJS plugin being registered in the gatsby-config.js file. So as Gatsby Themes are attachable node modules, they keep themself and thus your project up-to-date in case new theme versions are published.
We all know, that modifying functionality a node module (remember, what a Gatsby Theme is) provides, can be tricky in terms of losing modifications. So a rule of thumb - like for all node modules, don't touch and modify the theme itself within node_modules. Those adjustments will be lost once you update the Gatsby Theme within your node_modules folder. For luck, GatsbyJS provides a way on how to extend and modify the theme. That way requires your code structure to follow GatsbyJS conventions. The conventions lead to the effect that your own modifications "hook-in" during build time and "overwrite" the code of the Gatsby Theme. Either in terms of theme functionality or style-related. That just depends on what the theme does to your GatsbyJS project and what you want the theme to (not) do to your GatsbyJS project. An example:
A Gatsby Theme has the following file in its own repository (packed in the node module), implementing a blue background to your site header:
src / components / header.js
If you want the background to be red, modify your own GatsbyJS project with the following nested directory setup:
src / %themeName% / components / header.js
Note that what I've marked in between the %-symbols has to be replaced with the name of the Gatsby Theme you use. From now on, whatever you do in your own header.js file will overwrite what the header.js of the Gatsby Theme file does, which is cool 🚀! Making sure you add code changes this way, also makes sure you're on the safe side if it's about to update the theme (plugin). Once you update your theme via npm or yarn, your updated theme will make sure you use the latest code changes it provides. Still, your own modifications in your GatsbyJS project will consist 🎉. In "GatsbyJS language," this way of modifying a Gatsby Theme is called Shadowing.
In Retrospect, both are great GatsbyJS starting options but be aware of the essential differences
If you consider GatsbyJS as the way to go for your next project, definitely consider either taking a Gatsy Starter or a Gatsby Theme as your starting point. But before creating your project, take into account your long-term development strategy to decide on whether to go with a Starter or a Theme. To not leave you alone with an "it depends" summary, I'd assume that going with a Gatsby Theme as a starting point is the better way. Simply said because it ensures your project will benefit from dependency updates the theme handles and provides. But especially be aware that going with a Gatsby Theme requires you to take into account more thoughts about the file structure of your project compared to just bootstrapping a whole Gatsby Starter repository.
What is mentioned in this post is a brief overview of the differences between Gatsby Themes and Gatsby Starters. If you want more in-depth knowledge, make sure you find 10 minutes of your time to read the Plugins, Themes, & Starters page of the official Gatsby documentation. It will provide a detailed explanation of the differences and how to use GatsbyJS using either a Gatsby Theme or a Gatsby Starter.
Top comments (0)