A few weeks ago I published my first starter for Gatsby and I want to share what I learn from this journey.
As many starters in Gatsby, it began as a personal portfolio. After I published it and share it on Tweeter, people start to ask me if it was Open Source, and I said “Ermm yes 🤔”.
After days and days of coding and designing, I finished the version 2 of my website using rebass (styled-components system), @gatsbyjs v2 and @contentful 🎉 It was a full refactor from what I had, but I'm really happy with the results 😁 emasuriano.com22:03 PM - 26 Aug 2018
11
94
Technically all the code was open for everybody in Github but it was not configurable at all (lots and lots hardcoded information about me). So instead of helping developers, it was an awful experience when you have to guess where to change the code.
It was at this point I started thinking about creating a Gatsby starter to ease the setup of the page. My goal was to achieve a 2 minutes Setup with defined steps, so I had to work a lot on making something configurable and also extensible.
#1. Make it attractive to developers 💅
https://medium.com/media/38563052ed7a5b0abb5a59135ca9e175/href
You can think about your starter as a page you are selling to developers (you won’t get any money because it’s not the point of open source). So you have to make it attractive ✨ For that I follow these 3 rules:
Make it work.
Make it fast.
Make it pretty.
Make it work is for making your app actually functional and without any bugs or exception. Fortunately, I kind of had it this rule because my page was already working without any issues.
After achieving this, a very good tip for this point is to make a list of all the features you implemented. So a developer can take a quick glance what it’s inside without reading any codebase. 👍
Make it fast remains for building an application with an overall good performance. Achieving this point with Gatsby it’s not that hard, because Gatsby it’s already blazing fast out of the box 🔥 But still, you can write code that performs horribly.
For measuring the performance of my application I used Google Lighthouse. It gives you a report with statistics of different aspect in your application, like performance, accessibility, PWA and more. 👍
Make it pretty , this rule can be explained with this phrase:
If an application looks bad or if it doesn’t support my screen then I won’t use it.
Yes, it’s that simple! You have to provide something that looks attractive to others and also responsive, which is my opinion is a MUST in the current web development state.
A great tip if you are working with React is to pick a design system with built in components. That will save you a ton of time because there was a full team which took the time to think how the spacing should be, color palette, font, responsive and many many more! 👍
#2. Do not hardcode Personal Information 🤷♂️
When I looked into my pages I could easily detect that I had a mixed between component and information about me. A quick example it was the About me page, which looked like this:
The solution was “easy”, all the information has to come from other resources, and fortunately doing that with Gatsby is incredibly easy!
I decided to use a CMS to store all my data and then display it on the starter, in this case, I picked Contentful and I’m really happy with it 😃.
The first step is to create a ContentModel where I can declare the shape of the data about the owner of the portfolio.
After that, I need to fill my Content Model with Data by creating a Content. I did this to provide an example of how it should look when you fill all your information, and also without data the starter is completely empty 😂
By doing this, the person who wants to change information about himself doesn’t have to look into the component structure to find where the picture is being mounted. Just simply go into Contentful and change the asset for the picture and that’s it ✨
#3. Provide a Quick Setup 🚀
This is a crucial step if you want to encourage people to start using it. As a maintainer, you have to provide simple steps to get up and run the starter.
Also, the setup might change depending on what you picked to build your starter. In my case, as I used Contentful as the data provider I had to explain an easy migration of all my ContentModel and Content to the space of another person.
Quick tip: Remember to add gatsby new command as the first step of the setup. It’s the way the documentation suggest to do it and also it’s better than cloning the repo.
So the steps I defined for my starter are:
- gatsby new mate-portfolio
- yarn setup
- yarn develop
Try to be as specific as you can when introducing a new step that normally doesn’t exist, in my case yarn setup. Also, I paste how the result of the console should look like if everything went smooth.
#4. Add it to the official Gatsby starters list 📦
This might be the easiest and most grateful step, which is basically going official!
For any who doesn’t know, Gatsby has a list of all the starters inside its website, and people (me included) go there looking for the starters. This step is like register a domain for your website so it can be discoverable by users in Google.
The way to add your starter is just by opening a pull request to the Gatsby repository and editing the file starters.yml where you write a brief description and the URL for the starter.
- url: Link to a demo of your starter
repo: Link to GitHub repo
description: Your starter description
# These correspond to the category filters in the library
# Make an effort to use the existing tags, and add more if needed!
tags:
- Redux
# Add your site features
# These will be included on your starter's detail page.
features:
- Blog post listing with previews (image + summary) for each blog post
After your pull request is merged, you’ll be able to see as a new entry of the showcase. Here you can see mine!
One last thing, at the moment the maintainers accept your pull request you will be part of the Gatsby community! Gatsby gives “free swag” to any contributor (they have a shop where you can pick for free some stuff and deliver it to your home), which is the best way to show gratitude to developers, thank you so much Gatsby 🎉
I highly suggest you go and check out the Spectrum community, it’s a forum with awesome developers so you can ask for anything and also answer.
That’s it! This was my experience with building a Gatsby starter I hope you find it helpful. In case you build one too, please share your experience in the comment 😀
Top comments (1)
awesome and easy to follow insights, thx!