One of Gatsby’s greatest strengths is combining multiple sources of information into one universal GraphQL API, and then easily templating that content into pages of your website. Be it local files, multiple CMSs, or custom APIs, in the end you’ll only need to learn how to use Gatsby’s GraphQL API. This greatly reduces the mental burden to learn different API responses and enables teams to work together more efficiently. GraphQL is a strongly typed language so using TypeScript with Gatsby is a perfect match.
As part of Launch Week we’re happy to announce that Gatsby now has built-in support for GraphQL Type Generation. This greatly improves the TypeScript capabilities of Gatsby and brings GraphQL’s type safety to your frontend code.
If you’re working in a team of developers or just love type safety, this is a feature for you! Please note: I’ve also recorded a short demo video of Gatsby GraphQL Type generation that you can view at the end of this blog post or watch on YouTube.
How to Use GraphQL Typegen
To directly cut to the chase, here’s how you activate the new feature:
During gatsby develop you’ll now see a new activity printed to the terminal (with the message “Generating GraphQL and TypeScript types”) during which a couple of new files are created. Most importantly for you is the file src/gatsby-types.d.ts that is automatically generated and updated each time you change your GraphQL schema/queries (we recommend adding this file to your .gitignore). Add this file to your include list inside tsconfig.json so that TypeScript picks its information up.
You’ll now be able to access the global namespace Queries anywhere in your files. It contains types for your named queries with the nomenclature of ${queryName}Query. For example, the query for IndexPage, is called IndexPageQuery , and can be accessed at Queries.IndexPageQuery. You would include it like so:
Note that your queries have to have a name to have the feature working correctly.
The autogenerated types look something like this:
And that’s really it! You now have type safety for your page props. If you want to read up on more details, check out the GraphQL Typegen guide and the using-graphql-typegen example.
Making collaboration easier
As I said at the beginning of this post, Gatsby is great at aggregating different data sources into one unified layer. And now, it’s a lot easier to navigate inside this data.
Especially if you’re new to a project or working with your team on isolated components and have to trust an API contract (like properties on a React component). GraphQL Typegen can help with these challenges in multiple ways. If you’re already using TypeScript, you now don’t have to worry about writing the response types manually. And if you haven’t used TypeScript before it’s now easier to migrate! By having those explicit types for your query responses, your components and the users of these components (e.g. your colleagues) are less ambiguous in what data they receive and how they use it.
Quicker prototyping
I’ve saved my personal favorite improvement for last: You can get a GraphiQL-like experience inside your code editor.
You’ve probably already seen GraphiQL while using Gatsby’s local development environment (if not: it’s a visual interface, much like an IDE, to build GraphQL queries and is available on your local Gatsby development server at eg, localhost:8000/___graphiql).
Inside GraphiQL you get autocompletion for queries and their keys. Now, you get this autocompletion can come to your code editor now, too. When the Gatsby development server is running and you’re writing a page query for example you’ll now also get hints when writing it.
Please note: Your editor needs to support the GraphQL language server, our documentation explains how to use VSCode.
TypeScript and Gatsby
We have improved Gatsby’s TypeScript support and integrations greatly since the beginning of the year. Here’s a short list of things we improved (and which you can learn more about in this guide):
- TypeScript boilerplate when using npm init gatsby
- gatsby-ssr.tsx and gatsby-browser.tsx
- Support for writing gatsby-node.ts and gatsby-config.ts
While developing those features and after the release we’ve incorporated your feedback into making these better. For GraphQL Typegen we were able to rely on support from the open source community as the community plugin gatsby-plugin-typegen and GraphQL Code Generator greatly reduced the time it took to build out this functionality. Thanks!
Do you have suggestions for GraphQL Typegen? Let us know in the RFC discussion. Don’t forget to check out all the other exciting Gatsby product news from Launch Week and follow our main Gatsby account on Twitter (@GatsbyJS) for the latest Gatsby news and updates.