chore(gatsby): add TypeScript definitions for config & plugin APIs

[JamesMessinger]

Description

I added TypeScript definitions for the gatsby-config.js, gatsby-node.js, gatsby-browser.js, and gatsby-ssr.js APIs.

Some of the definitions could use more details (for example, many functions are simply defined as Function), but at least every method, parameter, and property are defined, which provides good intellisense and code-completion assistance in tools like VSCode. 😎

Related Issues

N/A

[pieh]

That's really cool! Users would need to annotate types of the exports in gatsby-X files, right? How does it look like?

I was working on something similar (but using jsdoc) and I did hit lot of problems but made it to somewhat work:

Reason for using jsdoc instead of TS definition was that we generate API reference ( https://www.gatsbyjs.org/docs/node-apis/ ) from that, so we wouldn't need to maintain definitions in multiple places (typescript defs could not always be up to date)

[JamesMessinger]

@pieh - Sorry, I should have included a usage example in my original description. VSCode (and other TypeScript-aware editors) support TypeScript definitions in plain JavaScript files (like gatsby-config.js) via a combination of JSDoc and "magic comments", such as:

• /// <reference types="..." /> (docs)
• // @ts-check (docs)

For example, here's what my gatsby-config.js file looks like:

// @ts-check
const gatsby = require("gatsby");

/**
 * @type {gatsby.GatsbyConfig}
 */
const config = {
  siteMetadata: {
    title: "Welcome to my website!",
  },

  plugins: [
    "gatsby-plugin-typescript",
    {
      resolve: "gatsby-source-filesystem",
      options: {
        name: "docs",
        path: `${__dirname}/src/docs/`,
      },
    },
  ],
};

module.exports = config;

Because I've declared my config variable to be of type gatsby.GatsbyConfig, I get code-completion, type-checking, and intellisense in VSCode. Which is really nice!

[eknowles]

thank you for this 👍

[JamesMessinger]

Oh wait! Before you merge this!

I hadn't heard any feedback on this PR, so I thought it wasn't going to be merged. So I was preparing to submit type definitions to DefinitelyTyped instead. But it's always preferrable to have type definitions in the library package itself, so I'm glad to see that you're interested.

Here are the latest type definitions (attched ZIP file), which I was preparing to submit to DefinitelyTyped. I've done a lot of cleanup, including separating the definitions into multiple files and correcting a few mistakes in my original definitions. In addition, I've added types for some Gatsby plugins too.

gatsby-types.zip

• gatsby-plugins
  This folder has the type definitions for the Gatsby plugin APIs (gatsby-browser, gatsby-config, gatsby-node, and gatsby-ssr)

• gatsby-source-filesystem
  This folder has the type definitions for the gatsby-source-filesystem plugin

• gatsby-mdx
  This folder has the type definitions for the gatsby-mdx plugin

[LekoArts]

Hi @JamesMessinger 👋
Would be great to have this in. Is that what you zipped up also in this PR? And could you also please have a look at the merge conflict? Thanks!

[KyleAMathews]

This is great stuff! Would love to have it merged!

[orta]

I've tried to merge in the zip changes, and add my own API reference JSDoc comments based on this PR in #13619

[wardpeet]

I'm updating the interfaces as there were some issues when trying to use it. (give me a sec to wrap up ^^)

for example this wasn't working:

/** @typedef {import('gatsby').GatsbyNode} GatsbyNode */

/** @type {GatsbyNode} */
const typedExports = exports

typedExports.createPages = (args, plugins) => { }

I might be just missing a lot of ts knowledge.

[wardpeet]

@orta maybe you know how to solve this.

Typings are correct as you can see below:

There is a problem as typescript can't detect the types of the params as it's a union of functions. So args & plugins are treat as an any value (if I remove the union and put only 1 function inside the d.ts file it works)

With only one function in d.ts file

[orta]

@wardpeet my PR is the successor to this #13619 - can you move any improvements there? I already fixed the above

[wardpeet]

sweet let me rollback my changes.

[wardpeet]

Sweet, thanks for doing the hard work of creating types for our apis so much appreciated!

[gatsbot]

Holy buckets, @JamesMessinger — we just merged your PR to Gatsby! 💪💜

Gatsby is built by awesome people like you. Let us say “thanks” in two ways:

1. We’d like to send you some Gatsby swag. As a token of our appreciation, you can go to the Gatsby Swag Store and log in with your GitHub account to get a coupon code good for one free piece of swag. We’ve got Gatsby t-shirts, stickers, hats, scrunchies, and much more. (You can also unlock even more free swag with 5 contributions — wink wink nudge nudge.) See gatsby.dev/swag for details.
2. We just invited you to join the Gatsby organization on GitHub. This will add you to our team of maintainers. Accept the invite by visiting https://github.com/orgs/gatsbyjs/invitation. By joining the team, you’ll be able to label issues, review pull requests, and merge approved pull requests.

If there’s anything we can do to help, please don’t hesitate to reach out to us: tweet at @gatsbyjs and we’ll come a-runnin’.

Thanks again!

[wardpeet]

published in gatsby@2.3.34