Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

TypeScript definitions for config & plugin APIs #10897

Open
wants to merge 1 commit into
base: master
from

Conversation

Projects
None yet
3 participants
@JamesMessinger
Copy link

JamesMessinger commented Jan 7, 2019

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

TypeScript definitions for config & plugin APIs
I created TypeScript definitions for the [`gatsby-config.js`](https://www.gatsbyjs.org/docs/gatsby-config/#gatsby-config), [`gatsby-node.js`](https://www.gatsbyjs.org/docs/node-apis/), [`gatsby-browser.js`](https://www.gatsbyjs.org/docs/browser-apis/), and [`gatsby-ssr.js`](https://www.gatsbyjs.org/docs/ssr-apis/) 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. 馃槑

@JamesMessinger JamesMessinger requested a review from gatsbyjs/core as a code owner Jan 7, 2019

@pieh

This comment has been minimized.

Copy link
Contributor

pieh commented Jan 8, 2019

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:
screenshot 2019-01-06 at 17 22 52

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

This comment has been minimized.

Copy link
Author

JamesMessinger commented Jan 8, 2019

@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

This comment has been minimized.

Copy link

eknowles commented Mar 11, 2019

thank you for this 馃憤

@JamesMessinger

This comment has been minimized.

Copy link
Author

JamesMessinger commented Mar 12, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can鈥檛 perform that action at this time.