How to use TypeScript with Gatsby

I was planning to write a blog post showing you how to setup Gatsby to work with TypeScript, but then I realized it was easier to just make a Gatsby starter. So since I've already done all the hard work for you, this blog post is going to more about what Gatsby and TypeScript are than getting them to work together.

If you just want things you can copy and paste to get up and running as quickly as possible, jump down to the section titled "How to use TypeScript with Gatsby".

Why should I use Gatsby?

Gatsby is a static site generator based on React that gives you the best of all worlds. Static site generation means your visitors and Googlebot can pull down fully-formed HTML pages immediately. Being based on React means you can make components on your site interactive using state-of-the-art front end technology. It also means you can fetch new data that's personalized to your users like you would normally do with a frontend written in React.

Why should I use TypeScript?

For me, the number one reason is so I know what properties an object has. If you've ever struggled to remember exactly what to type and in what order when you were trying to pull a value out of an object, then TypeScript will be amazing for you.

Imagine you have an object that represents a blog post and you need to get out the value at post.metaData.publication.date. How do you remember that the person who made that object decided metadata should be two words instead of one? Why did the author decide that the publication date should be nested inside a publication object instead of being a publicationDate property on the metaData object? These kinds of mental gymnastics are not necessary with TypeScript because TypeScript can helpfully pop up a list of all the properties available every time you type a dot at the end of a variable name.

There's tons of other reasons to use TypeScript, but I won't get into them now. Bottom line: it gives you so many helpful guardrails that it's really hard to go back to regular JavaScript afterwards.

Why should I use your gatsby-starter-typescript?

Good question! I don't know. I haven't looked very deeply at the other ones. I can just tell you what mine includes:

• A very strict tsconfig.json
  • I turned on as many checks as I could. (I couldn't turn on a couple because of conflicts with the types created by gatsby-plugin-graphql-codegen.)
• GraphQL type generation for queries in gatsby-node.ts
  • The GraphQL queries in your gatsby-node file are likely to be very important to get exactly right. Otherwise you could end up with missing pages. That's why it's so critical that we type our GraphQL queries there too.
• gatsby-plugin-typescript
  • This installs TypeScript and gets your IDE setup to highlight any issues the TypeScript compiler finds.
• gatsby-plugin-typescript-checker
  • This runs the TypeScript compiler when you're running yarn develop so you can see a list of all TypeScript errors in your project as your developing instead of having to visually look for them in your IDE.
• gatsby-plugin-graphql-codegen
  • This generates types for all your named GraphQL queries. Since data returned from GraphQL queries tends to be very deeply nested, this is super helpful when you need to massage your GraphQL data into a different format for your React components.

How to use TypeScript with Gatsby

There's three steps to this process:

1. Installation
2. New Project Creation
3. Deployment

Installation

First, install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Then install Yarn:

brew install yarn

Next, install the Gatsby CLI globally:

yarn global add gatsby-cli

The last thing we'll install is Surge. Surge lets us deploy our Gatsby site with a one-liner.

yarn global add surge

New Project Creation

Create a new project based on my gatsby-starter-typescript. There are several other "gatsby-starter-typescript" projects, but only one by me!

gatsby new my-typescript-starter https://github.com/kurttomlinson/gatsby-starter-typescript

This creates a new folder with the same name that you gave to gatsby, "my-typescript-starter". To start developing, you can run cd my-typescript-starter and yarn develop. Once the development server boots up, you'll be able to see your changes live at http://localhost:8000.

Deployment

To deploy your site to a random Surge subdomain, run the commands below:

cd my-typescript-starter
surge ./public/

Surge will ask you for a domain and will helpfully provide a random subdomain for you to use for free. You can just hiter enter. When it's done, you'll see a message like...

Success! - Published to hulking-sister.surge.sh

Going to your version of hulking-sister.surge.sh in your browser should pull up your new Gatsby + TypeScript site from the internet! Congratulations!

Note: to remove your site from surge, you can run surge teardown hulking-sister.surge.sh

Photo by Pereanu Sebastian