A guideline for effectively building responsive & blazing fast website in a weekend, using Gatsby.js

Follow the right guideline with the right tools to save your effort, and deliver the impressive, blazing fast website effectively! For React.js engineers.

Always use the right tool to do your job!

Nowadays there are many excellent React.js programmers but not all of them can quickly deliver a responsive, blazingly fast portfolio website in a weekend without using proper toolkit.

It can be quite common that we want to quickly build a portfolio to showcase our awesome products, but we wouldn’t want to spend too much time on coding every detail of the entire website. What we need is just the right tools to do the job and avoid repeat work. Suppose you are a software engineer who is already familiar with React.js, now this article is exactly what you want to guide your work!

I tried Gatsbyjs through the official tutorial, and then built my simple blog in a weekend, and this is the speed score I got. You can do better.

What we want to build

Let’s say we want to build a portfolio website to present some nice blog articles, or to showcase a list of side projects. We expect it to have the following features.

• mainly it presents a list of items, could be article or projects,
• the website contains several static pages, we want to optimize the performance, the website need to be responsive and sometimes mobile-first,
• need to be able to optimize for search engines, or SEO,
• can have a direct embedding section to a social network like Twitter,
• it allows visitors to leave some comments, but we don’t want to maintain a user authentication flow.

Most importantly, suppose that we only have one engineer who can write great React.js, but we don’t want to spend too much effort on building the website. That’s when the great Gatsbyjs can come in handy! We can literally build the website as easy as building a Lego house.

The complete framework/tools/libraries to use

• Gatsbyjs, after you’ve become familiar with React, of course
• Github to host your code
• Host service like Github Pages or Netlify. If you don’t have your own server, you need a service to host the website. Both platforms are free for deploying with a sub-domain!
• A Gatsby starter project as a quick boilerplate for your own purpose. Usually, I would recommend these few boilerplates, but you can view the whole list at here:  
  • for ecommerce: https://www.gatsbyjs.org/starters/parmsang/gatsby-starter-ecommerce/
  • for blogging: https://www.gatsbyjs.org/starters/gatsbyjs/gatsby-starter-blog/ or https://www.gatsbyjs.org/starters/alxshelepenok/gatsby-starter-lumen/
  • for showcase: https://www.gatsbyjs.org/starters/contentful-userland/gatsby-contentful-starter/
  • if you want to customize as most as you can, just use the advanced starter template: https://www.gatsbyjs.org/starters/Vagr9K/gatsby-advanced-starter/
• A UI framework to save your time from basic styling and responsive layout, I would recommend Bulma to do the job, with several templates

And for the Gatsbyjs project, we need many Gatsby plugins to enrich the feature list. But it’s really handy as most plugins can be bery simple to use, when they just require some minor config changes. Most of the plugins can be found (and already configured) in the starter templates, I’ll give a list here for you to check if you missed anything you need.

• gatsby-plugin-offline, to enable drop-in support for making a Gatsby site work offline and more resistant to unstable network connections, using service worker.
• gatsby-plugin-react-helmet, provides drop-in support for server rendering data added with React Helmet.
• gatsby-plugin-sitemap, create a sitemap for your Gatsby site.
• gatsby-remark-images, processes images in markdown so they can be used in the production build.
• gatsby-transformer-remark, parses Markdown files into contents.
• gatsby-plugin-google-analyticsm, easily add Google Analytics to your Gatsby site.
• gatsby-remark-prismjs, adds syntax highlighting to code blocks in markdown files using PrismJS.
• gatsby-plugin-feed, create an RSS feed (or multiple feeds) for your Gatsby site.
• several data source plugins, many ways to provide data to your website who can function as a simple read-only DB.

Because Gatsbyjs would generate static websites from React project, we can also use popular React components here to enhance the functionalities. For example:

• react-twitter-embed, to embed Twitter timeline/share button in your page
• disqus-react, to embed Disqus comments module in your webpage
• any popular 3rd party UI libraries, but please keep bundle size in mind

Guideline

What does a guideline mean? It is a streamline to indicate a course of actions, if you are equipped all the tools and skills, but don’t know how to use them effectively.

Prerequisites

1. Familiar with React.js programming, if not it’s really time to learn Reactjs now!
2. You have taken an hour to read over Gatsbyjs official tutorial. Trust me, you only need an hour to know what does the concepts of Gatsbyjs mean, it’s a good official tutorial.

Now you should know about the concepts like Gatsby starters, plugins, GraphQL query, page slugs, and how to use Gatsby CLI.

Let the rock begins

In this section, we’ll walk through a guideline of how to build a reliable website in high efficiency. So grab a coffee and let’s begin!

1. Find your data source and design data structure.

I list it as the first step because it’s always important to keep in mind what you want to showcase, and what does the meta-data combined of. To be more specific, if you want to build a blog system, the data you need is possibly combined of {title, subtitle, description, slug, content, author, datetime, tags, category}. And for a product showcase site, you may need {product name, category, sale price, original price, description, where it's produced, where it's imported, product license, etc.}. I think it’s fair to say that you need to design the data structure before design the website. And then you’ll find many ways to provide data to your Gatsbyjs project, using plugins listed here. Please notice that because the ‘public’ files you build is static, so it can’t act like a PHP page which refreshes every time showing different data when the supporting database updates. Here you can only get the new website for the data change after building the static files again. As a hint, you can use gatsby-transformer-remark to build a blog from several markdown files, or use gatsby-source-mongodb to pull data into Gatsby from MongoDB collections. Never restrict your thoughts, why not use Google sheets to provide data? Actually that can satisfy most portfolio sites, as what you eventually want to do is to present a list of data in a website. Isn’t it?

2. Design your component for the meta-data.

Generally speaking, consider how to design the UI components that could be repeatedly used in your website. For example for blogs, the reused components could be:

• each blog page component, presenting the article details
• blog item component for the blog list, containing minimal details like title, description, creation date, etc, and link to the article.
• a card component to present best blogs in your index page, also containing some information and a link

Thanks to React, you can easily implement and test the components in a separate Component class, even styling inside the class using inline styles or some better approach. Please take a look at the Thinking in React article if you’re not very clear about what I mean, and remember to reuse components.

3. Use a starter library that suits your need.

I’ve already listed some starter libraries of my recommendation in the last section, you can also check this link for complete choices. A hint: if you’re familiar with how Gatsbyjs works, take the most basic template and do your cool stuff inside. Otherwise, please take the template as much feature-rich as possible to save your effort. Ideally, for a simple website, most layout/routing/data source configuration work has been done in the starter library of your choice.

4. Design the webpage layout for listing the data

After having a clear idea about how the reused components should be presented, we can then focus on how the skeleton layout should be arranged, and put the components properly. We may expect to have some pages for a different router, for example for blogs we expect at list two different pages, a blog list page and an article detail page. An example is when using official blog starter template, you need to implement your design at least in these three files.

Usually a navigation bar/menu is the first step, then another page container for each page, is sufficient for small websites. This is when Bulma framework can be very handy (of course Bootstrap can also do the job, if you’re already familiar with it). Just import the bulma.css style in your main style file (I would recommend using less/scss preprocessor CSS language), and take the ‘out-of-the-box’ components as you need. Another helpful website you can make use of is the Bulma templates site, which contains several useful layout templates for many different kinds of websites. Of course you can’t directly copy & paste all the time, but it can really save you some effort.

Another thing about layout I’d like to introduce is the CSS flexbox layout. As responsive design is becoming more and more useful nowadays, flexbox can be a very efficient and easy-to-understand way to layout your things. It’s also very easy in flexbox to align and centering things. CSS flexbox is already supported in all major desktop/mobile browsers.

5. Bring the work together

OK, with some hard work we should now have some nice pages in hand. Next step is to bring it together as a working website. We’re expecting to run the website locally through gatsby develop in Gatsby CLI.

If you’re following a boilerplate to start your work, mostly you won’t need to worry about routing for pages as they are already there. If you need to implement some custom pages, Gatsby core automatically turns React components in src/pages into a new router to serve the new file. You can check routing docs for more information.

6. Add forms, social network, and comments

Because we have only limited time, so I skipped an important element for common websites: forms. It can be a very common use case that a website needs the visitor to submit some information, but mostly using forms would require a user login step so that we can know which user submitted this information, and that can cost some effort. I’ll talk more about it in the next section, but if you don’t want to spend much effort on forms, just use Google forms, possibly in a iframe. I’m not advertising Google product, but you really don’t need to spend much effort when we already have a reliable way to ‘implement’ forms for our usage.

Same thing works for social network and comments system, by relying on 3rd party libraries. We can easily use React embedding components to embed social network, like twitter-embed to embed Twitter timeline in your page, or use disqus-react to embed disqus for comments. Of course, it would introduce some issues like introducing 3rd party dependencies and ‘not saving data in our own server’, but personally I think it’s sufficient for many use cases. I’ll also talk more about it in the next section.

7. Add SEO and Bring it online in production!

SEO is another built-in feature for Gatsbyjs projects, as it can help you add required metadata for SEO on each static page, and it’s server side rendered so all your information is available to search engines or crawlers. Basically you only need to add required information in config file to make SEO work. Please check this doc and this plugin for details.

If you have your own server, simply build your Gatsby project and serve the public/ folder using Nginx or whatever, and that’s it!

Otherwise, all possible deploying and hosting choices are listed here. I would recommend Github Pages and Netlify, especially Netlify which I used in two projects already and doing well. Netlify can have free CI integration with Github private repos, which allows build and deploy automatically from master code changes.

Both Github Pages and Netlify platform are free and widely used & recommended, here’s a simple comparison between these two platforms.

Because I just have a weekend

Congratulations about how much you already achieved through the guidelines! Only in a weekend you have successfully built a website with blazing fast performance and responsive design, which performs well in all platforms. Your audience would be impressed.

If given more time and effort, absolutely we can do more! Here are some aspects that I think you can continually work on.

1. User authentication. Sometimes you need to create a site with gated content and access control, Gatsby has a document about client-only routes which can control which pages user can access after logged in. Personally I would recommend using 3rd party oauth authentication which could save lots of effort, another approach is using some server-side control like Netlify’s identity feature.
2. Localization, or i18n. It can be easily done by using any React i18n components, but pay attention that i18n is always related to routers. You can use a gatsby plugin to do the job.
3. Forms. Previously I mentioned that you can use Google Forms to act the form role, that could be not feasible sometimes. If you host a server side code to deal with forms, you can send requests from front end form components to your server, as any React project does. Netlify also has a built-in form handling to help you host server-side code without actually running a server.
4. Styling. In last section we can build the system with basic skeleton containing some layout and components, but the complexity may be not enough. You can check showcase and see how other complex website works with Gatsbyjs. From my point of view, the complexity is the same, we just need to spend more effort on better layout styling and design more components, that’s all.

Nothing special.

Thanks for reading! If you have any questions or suggestion, please leave a note or twitter me anytime.