Decide on how to handle TypeScript for Gatsby plugins and themes

[jxnblk]

Based on discussion in #668, we should decouple the TypeScript conversion of Gatsby-related packages from the core packages, due to how Gatsby currently handles TypeScript in plugins.

Currently, the plugins and themes are written in standard JavaScript, and Gatsby uses these packages as-is, without a compilation step needed in this repo. This can be beneficial for users who "eject" (copy and paste) files from these plugins and themes, when using Gatsby's shadowing feature, because it means the files copied over are the same as they are written.

In the future, once Gatsby supports TypeScript language in plugins, we should still consider backwards compatibility and those who use Gatsby with JavaScript -- introducing another language could be unexpected.

There are several PRs already in-progress for converting these packages, and they should remain open until a solution is decided upon:

• gatsby-plugin-theme-ui (WIP: refactor(gatsby-plugin-theme-ui): add typescript #705)
• gatsby-theme-code-recipes (refactor(gatsby-theme-code-recipes): convert to typescript #709)
• gatsby-theme-style-guide
• gatsby-theme-ui-blog ( Convert gatsby-theme-ui-blog to TypeScript #711)
• gatsby-theme-ui-layout (Convert gatsby-theme-ui-layout to TypeScript #710)

Potential solutions

Off the top of my head, there are a few ways to handle this, but I'm open to hearing more suggestions:

1. Keep all Gatsby related packages written in JavaScript -- this is not ideal for TypeScript users
2. Convert packages to TypeScript and add a compilation step -- this is probably not ideal for anyone
3. Add type definitions for the packages, but keep them written in JavaScript -- I'm unsure of how big the downside is, but TypeScript users who eject files would still get JavaScript
4. Create separate TypeScript-specific packages in addition to the JavaScript ones -- this has a bigger maintenance cost
5. Wait for future support in Gatsby that could help with this -- it's unclear what this would look like or how long this would take

Additional context

Some of these packages have very low usage and are somewhat experimental:

• gatsby-theme-code-recipes: 1 download per week (I think it's theme-ui.com)
• gatsby-theme-ui-layout: 28 downloads per week
• gatsby-theme-ui-blog: 88 downloads per week

[hasparus]

I'd like to add one potential solution. I'm not sure if the 3 is the one I'm thinking about.

Preact is written as JavaScript with really good JSDoc comments (powered by TS).
We could steal that approach for plugins and themes.

Pros:

• It's still JavaScript, and most developers are either familiar with JSDoc, or will just disregard it as a normal comment. We preserve accessibility for JS users. IDEs of JavaScript users should pick these types and provide autocomplete, and the comments are not hard too remove if somebody doesn't like them.
• With checkJs: true in plugin tsconfig, we'll get type errors during development if a change to theme-ui packages breaks the plugin.

Cons:

• TS users will need to turn checkJs to true if they want typecheck ejected files. (that's not a huge problem, I think)

[jxnblk]

That sounds a lot better than what I was thinking! If we go that route, would it make sense to keep the in-flight PRs open? Or, is there a way we should preserve that work if Gatsby provides better support for TS-based plugins in the future?

[lachlanjc]

Closing since I think we know what we want to do here, & there's separate issues/PRs for implementing it? (Feel free to reopen.)