Building blog with GatsbyJS — lessons learnt
Do you plan to build your new blog using GatsbyJS? Is it going to be your first project with this tech? Maybe you’ll find a few useful hints in this art.
What can you find here?
Don’t expect tons of code or one more GatsbyJS tutorial. It will be rather ( I hope nice ) a monologue from a JS developer about GatsbyJS development experience.
I’ll list up various challenges that I identified before I started development of this blog and then how I managed to overcome them. That was my second project in GatsbyJS so I had some experience. Not too much though :)
OK, let’s crack on…
Choice of CMS
GatsbyJS is a static site generator so you need some content to feed it. I was wondering what will be my choice?
Wordpress
My first Gatsby project was integrated with Wordpress so that was my first thought.
Although I would have to host it on some external server as keeping Wordpress on your localhost doesn’t sound too professional ( though for a developer is good enough :) ). That means extra costs…
However the main reason that I gave it up was… not to stay behind :) Wordpress was definitely in my comfort zone but I said to myself:
“Come on man, go headless!”.
NetlifyCMS
The next choice was to use NetlifyCMS as I planned to host it on Netlify. That would be a nice match-up, wouldn’t it? An integration with GatsbyJS is very simple as well. You can use default starter.
Before I jumped in to a development I decided to look around the CMS itself. How it works, how flexible it is and what it offers. You know regular boring stuff. I need to say that my first impression wasn’t very good. The second was not great either. I felt it’s a bit too simple. I didn’t want to wake up half year later and realise that I need something more. I said:
“Let’s try something different…”
GraphCMS
I’ve read some good reviews about it and decided to give it a go. Not immediately but I started to like it. I watched one of YouTube tutorials to make my start a bit easier.
Integration with Gatsby was relatively easy. All you need is a gatsby plugin and docs are clear if you get lost.
What I really liked in the CMS itself was API Explorer. You can quickly check all your GraphQL queries. This is awesome!
Ok, GraphCMS was my choice!
Headless CMS
What is good about headless CMS is that you don’t have to host it on your own server. It can sit nicely in a cloud but…
If you’re a small blogger like me you can choose developer licence which is for free. It has a limit of 500 records (blog posts) and doesn’t have a Web Hooks ( Web Hook is an API call to your hosting service saying that it’s about time to redeploy a page as it has some new content ).
For me it’s not a problem because I’ll probably never write that many posts and I can make custom API call from a terminal each time the blog should be redeployed.
If you want something more you need to pay :)
Hosting
That choice was very simple — Netlify. It can be integrated with your Github account and each time you update particular repo or send custom hook it will deploy your website. You can host that kind of blog for free which is awwwsome :)
In the end of the day your only cost is domain. If you choose Google it’s £10 / year.
How to embed Gists?
That was my second question. This is suppose to be blog for developers so code snippets will be essential! I like using Gists so how to embed them in my CMS and then render via Gatsby?
Answer was not so obvious and I haven’t done that via headless CMS before. In typical Wordpress I would just paste provided code to a content box and that’s it.
CMS field that you use for your blog content needs to have Markdown type. Then inside it you need to paste Gist URL in that format:
<script src="https://gist.github.com/user/gist.js"></script>
So basically original code format that Gist uses for embedment.
Inject Gist to Gatsby
The next step was to find a way for Gatsby to interpret CMS markdown, recognise gist snippet and handle rendering. I cracked my head around for a while and tried a few approaches.
You basically need two extra plugins — Gist and Markdown. It’s very nicely explained in this blog post. Worked as a charm…
TypeScript
It’s getting kind of a trendy these days to use it with React apps. I’ve got more Angular background so it’s taken for granted there. In Gatsby it requires some effort to integrate it.
Integration
As most great things in Gatsby TS comes with the plugin. If you look at the docs it seems to be so easy but at some point you might realise:
“Ok, installing plugin seemed to be easy part but how to actually start using TS here?”
Save yourself some time and if you’re not sure how to crack it just follow this tutorial. It was sooo helpful! Alternatively you can use TypeScript default starter. But you know… You can choose only one default starter :)
Progressive Web App
A while ago I was studying Service Workers. It was a good fun and I learnt a lot but to build nice PWA app with reasonable cache, push notifications and Background sync requires so much effort… Not with Gatsby!
All you need to do is install this plugin and define manifest inside `gatsby-config.js` file. The task is easy as ‘1, 2, 3’. I felt a bit guilty… PWA in 5 minutes… Don’t tell your clients about it…
Thing to keep in mind is that Gatsby doesn’t actually register Service Worker on localhost so you can’t really test it. When I deployed to live I noticed that by default service worker uses only caching but it’s good enough.
Styling
That’s a big one… I really fancy Styled Components and do not plan to use SASS for my future Gatsby/React projects but… my styling experience was less than flawless.
The big issue was that my styles looked different on develop than on my build. And it seems to be quite common issue. I spent so much time trying to fix it… Those are potential problems people face:
- Styles from various modules are not sorted correctly in a header after build. Then class names are different between build and develop. It can be problematic if you use Styled Components with other CSS plugins like @emotion/core or react-pose. I’m not saying not to use those plugins but if you face similar issue you might want to check it.
- Various cache issues. No surprises here :) Issues can be both on a browser site and a server. Some people suggested even to delete a site on Netlify and recreate it…
- The issue was caused by PWA plugin — not true in my case
- Your Gatsby CLI/modules are not up to date.
- You use beta version of Styled Components — in my case it broke my Global Styles.
What was my problem?
After days of frustration I couldn’t believe that it was that trivial… So my build looked like it was scaled up. Some people noticed that their Gatsby localhost browser tab was… Zoomed out!
I had no idea why and how it happened but my Chrome Tab was really zoomed out. I’ve build my styles thinking it’s 100% but it was 80%! Then on build it was 100% so it looked like scaled up… Good one, isn’t it?
Fixing all styling issues made me feel so good… It was a bit pain really to get it done but it shouldn’t be this way!
Redux
If you want to use Redux Default Starter can be helpful.
Search
There are a few techniques to handle it. I think the easiest is Algolia. This Youtube tutorial is quite neat.
Well… I haven’t implemented search yet. Maybe that will be my next feature on this blog :)
Summary
That would be it for today. I think I shared most of what I learnt this time. I hope the post is helpful. In my opinion the biggest issue was styling. What do you think?
