Introduction to Gatsby with TypeScript and GitHub Pages

JavaScript React TypeScript

When a browser opens a regular React application, it receives HTML with an empty div and a JavaScript file.

When the browser receives the above response, it runs the JavaScript file that modifies the DOM tree and creates a web page. This is a good solution for many applications but has a few drawbacks.

Firstly, the above approach relies on the device the browser runs on to be able to render the React application. Depending on the complexity of our app, some users might encounter performance issues when using older devices.

Secondly, serving just an empty div in the initial response can hurt the ability of search engines to index our website correctly. Because of that, our SEO might suffer, and we might not be positioned high in Google search results.

Introducing Gatsby

Gatsby, at its core, is a static site generator. It takes our React code and Markdown files and generates HTML pages during the build process. We then need to deploy the build result to the web server. Then, when users request the page, we respond with the full HTML instead of an empty div.

You can find the code from this article in this repository.

Getting started

To start using Gatsby, we need just one command.

The command line interface asks us a bunch of questions. The most important question is about the language we want to use. Let’s use TypeScript.

Using the above command generates a bunch of files and directories:

  • gatsby-config.ts
    • contains the metadata of our site along with plugins and other general configuration
  • images
    • the directory where we can put our images
  • pages
    • creating a file in this directory adds a new page to our website
    • index.tsx
      • the main page of our website
    • 404.tsx
      • the page that is displayed when the user accesses a page that does not exist

When we run , our page is accessible at  by default.

Creating the index page

Let’s inspect a very basic page and break it down.


The component that describes our page can have any name, but Gatsby expects us to use the default export. The page component accepts various props that describe the page, such as the path. We can also create a component and export it. Gatsby will add it to our document’s section.

Running creates the directory containing the build’s result. Let’s inspect the file that is created during the above process.


The most important thing is that Gatsby rendered the and components. Gatsby also adds various JavaScript files related to React and Webpack. It also injects elements such as and that aim to improve accessibility.

Adding a page

Adding a new page is very straightforward. To do that, we need to create a new file in the directory and make sure we use a default export.


When we add a new file to the directory, Gatsby checks the file’s name and creates a new page accordingly. Because we’ve called the file , we can now access .

We could nest our file in a subdirectory, for example, . This would create a  page.

We can also create files in subdirectories, for example, . This would create a page under the address.

Linking to another page

We can also create a way to navigate from one page to another by using the component.


Gatsby uses the Intersection Observer API to wait for the component to be visible to the application’s user. As soon as that’s the case, Gatbsy preloads the new page so that the user does not notice the additional loading time.

Using SCSS with CSS modules

Combining SCSS and CSS modules is a good solution for styling React applications. SCSS contains a bunch of advanced features and serves as an extension to the CSS language. By using CSS modules, we can scope our styles per component and avoid many headaches.

To start using SCSS with Gatsby, we need to install a few packages first.

We also need to add to our configuration.


Let’s create a straightforward SCSS file to test if it works as expected.


We also need to create a TypeScript declaration to import the above file. Without that, we would receive the following error:

Cannot find module ‘./index.module.scss’ or its corresponding type declarations.


We can now start using SCSS modules in our application.


Deploying Gatsby to GitHub Pages

GitHub Pages is a way to host our static pages directly from our GitHub repository for free. Thanks to that, our page can be publicly available either on the domain or our own.

We can also deploy Gatsby to GitLab Pages.

When we use the domain, our website is accessible at . For example, you can view the page created when writing this article at Since we host our application at something other than the domain’s root, we need to specify an appropriate prefix for all of the paths on the website for links to work correctly.


Above, use the name of your repository instead of .

We want GitHub to automatically deploy our website whenever we push changes to the master branch. To achieve that, we need to define a GitHub workflow. A workflow is an automated process that can run a set of steps to build and deploy our application.

The most straightforward way to configure our repository to deploy Gatsby to GitHub Pages is to use GitHub Actions. To do that, we need to go to the settings page in our repository and click on the pages tab.

When we choose GitHub Actions as the source for our GitHub Pages, we are presented with the option to use a default workflow for building and deploying Gatsby applications.

When we click the “configure” button, we can create a commit with the file that contains our workflow.

Pushing the file to our master branch causes our workflow to run. It builds and deploys our application to GitHub pages.

Let’s take a look at an important part of our file:

In the above configuration, we specify that when we push changes to the master branch, we want to trigger a new build and deployment automatically.


In this article, we’ve learned how to set up a basic project with Gatsby, TypeScript, and SCSS. To appreciate the results, we’ve set up a CI/CD pipeline using GitHub Actions. It deploys our application to GitHub Pages every time we push changes to the master branch. All of the above is enough to understand the basics of how Gatsby works. It also allows us to start creating applications right away.

Notify of
Inline Feedbacks
View all comments