Play: Experimenting with TypeScript

[moonmeister]

Summary

There has been some discussion about making Gatsby easier to contribute to via TypeScript. I've been playing around with this idea in Gatsby and wanted to share what I was doing. I've modified the babel configs and such to make this possible in gatsby core and in plugins.

I'm completely new to typescript so there's somethings I probably don't have correct or haven't figured out yet.

Branch: https://github.com/gatsbyjs/gatsby/tree/typescript

Related:
#10897

[moonmeister]

FYI: This could probably be implemented for plugins pretty quickly. IT's a non breaking change...all JS files keep building. Plugins that want to convert could do so at their leisure once the updated babel-plugin-gatsby-packages is released.

One thing I haven't figured out is how to generate type definition files. I think this can be done automatically once .js files are converted to .ts and everything has been typed appropriately.

[wardpeet]

My honest opinion is to move to jsdoc + typescript definitions. I think it's easier to grasp than typescript and more js likely. Besides ts & tsx files I feel that typescript doesn't optimize super well for the web as it compiles async await to generators which are polyfilled again with a lot of code. When using js you can choose how to polyfill with babel (unsure if typescript has this support as well now it can be used with babel).

More info can be found here:
https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html
https://github.com/Microsoft/TypeScript/wiki/JSDoc-support-in-JavaScript

I don't know how others feel about this.

[moonmeister]

@wardpeet How jsdoc and ts definitions work together?

[wardpeet]

hey sorry, I pushed comment a bit to fast 😛

I updated above comment

typescript is able to parse js files and use the jsdoc comments as typing information.

[moonmeister]

@wardpeet Hey, so checkout how I've modified the babel-plugin-gatsby-packages and gatsby-plugin-manifest I just pushed more updates to them in the last minute. This is still using babel for compilation. It's just removing all the ts. @babel/preset-typescript does this for us. I have converted to using ts/tsx files and included *.d.ts of the plugin.

The one thing I like about using typescript over jsdoc is that comments(i.e. jsdoc) can get out of sync from the code. It's "extra" work. I've added a "check-types" script that runs the typescript compiler and confirms everything is valid. That could be run by CI and git hooks just like linting is.

[wardpeet]

Jsdoc + tsc does exactly that. So they won't get out of sync. I'll create a sample starter to show this of. Also when I'm at my desktop let me dm me my calendly link so we might pair on this 😂 Maybe others are more in favor of using ts so my points might be moot.

[moonmeister]

@wardpeet Sweet. I'd love to.

[DSchau]

@moonmeister just saw this--love the label and so excited to have you working on some of this "fun stuff" (or as you say, Open Play ™️!)

Thanks for working in the open on this! I'm not a huge fan of JSDoc, but interested to hear what your thoughts are re: JSDoc vs. pure TypeScript.

[moonmeister]

Okay, @wardpeet and I had a good chat comparing methods. I'm going to try to summarize.

TL;DR

We have three options, 2 that are viable, both have pros/cons. The immediate action item for me (or any one who wants to help) is to create a example of gatsby-plugin-manifest using both viable options and that will get presented in a community meeting in the future for more discussion.

The Options

• TypeScript - We use the TypeScript compiler, file types, and syntax.
• TypeScript + Babel - We use the Babel compiler with TS plugin, TS file types, and syntax.
• JavaScript + JSDoc + TypeScript Definitions - Babel compiler, JS file types, JSDoc syntax in JS files, and TypeSCript Definition files and js doc imports as needed when JSDoc doesn't meet our needs.

TypeScript

The TypeScript compiler is not on par with Babel. Because of things like @babel/env and other controls we can optimize the code output. Because TypeScript doesn't have these options the code would be more bloated and less optimized. This goes against the "Blazing Fast" aspects of gatsby and not tenable.

TypeScript + Babel

Using this method we still get all the benefits of Babel as our compiler and keep benefits of TypeScript as our language and type checker. Project type definitions could be generated for APIs at build time and not manually maintained separate from code.

One concern with this method is we'd be using TS syntax and file types. This has it's benefits but means anyone contributing to Gatsby would be required to learn these things to contribute. It's a potential barrier to entry that needs to be considered.

JavaScript + JSDoc + TypeScript Definitions

This method means keeping JS syntax but adding JSDoc comments for all type definitions. JSDoc isn't as capable as TS but allows importing TS definitions. This means where JSDoc doesn't meet a need we can eject to TS definition files and import those into the JSDoc syntax.

The TS Compiler understands JSDoc and thus is still able to type check the code and require JSDoc notation.

What JSDoc can't do it generate type script definitions for use.

IMO

I think the big trade off between JSDoc and TypeScript is accessibility for contributors. JSDoc does keep JS but you also have to learn JSDoc and probably still TypeScript. Going TypeScript + Babel means just learning TypeScript. No JSDoc. Additionally, IMO TS is easier to learn then JSDoc.

Conclusion

I will work on creating a TS + Babel and a JSDoc version of gatsby-plugin-manifest.

What do you think? Anything I missed in my comparison?

[orta]

Yeah, I think babel + ts is probably the right route. I think the main advantages are solid tooling for contributors (which is why we ported jest) as well as being able to provide 1st class type definitions for people using the modules.

Ideally JSDoc annotations should be added anyway, mainly so people get inline docs when working with the API.

Would this allow gatsby-config.ts from a user's perspective also?

[moonmeister]

@orta Thanks for pointing that out. Using TS + Babel still allows for documentation using JSDoc. Types are just not defined through JSDoc.

Yes, I believe it would allow for gatsby-config.ts.

@orta Are you able to estimate whether people have had more/less troubles contributing since the switch? (i.e. is TypeScript a barrier to entry, or does the developer tooling it enables provide a lower barrier to entry)

[orta]

We think there are more first time contributors to jest, but don't really have anything quantifiable - Jest was already very deeply covered by flow, so there already was the types barrier to entry for JS folks.

In most of our projects owe transpile TS via babel, then after use tsc to emit *.d.ts during deploys