Twoslash: Markup for generating rich type information in documentation

here's an in-depth video with the (de-facto) author of twoslash for anyone interested https://youtu.be/An_XkLxLWjA?si=M8Cehe8xtYAi6_FH

also, did you know that there's an inline syntax? it's `// =>`

We've been using (the old) Shiki Twoslash for a few years now for our docs pages:

https://electricui.com/docs/components/LineChart

https://electricui.com/docs/operators/aggregations

Our product, Electric UI, is a series of tools for building user interfaces for hardware devices on desktop. It has a DataFlow streaming computation engine for data processing which leans heavily on TypeScript's generics. It's pretty awesome to be able to have examples in our docs that correctly show the types as they flow through the system. I certainly learn tools faster when they have good autocomplete in the IDE. Twoslash helps bring part of that experience earlier in the development process, right to when you're looking at documentation.

Our site is built with GatsbyJS, the docs are a series of MDX files rendered statically, then served via Cloudflare Pages. We use the remark plugins to statically render the syntax highlighting and hover tag information, then some client-side React to display the right tooltips on hover.

We build a Twoslash environment from a tagged commit of our built TypeScript definitions, from the perspective of our default template. The Twoslash snippets as a result have all the required context built in, given they are actual compiled pieces of code. The imports we display in the docs are the actual imports used when compiling from the perspective of a user. It bothers me when docs only give you some snippet of a deeply nested structure, and you don't know where to put it. Even worse when it's untyped JS! Using Twoslash lets us avoid that kind of thing systematically.

The CI system throws errors when our docs snippets "don't compile", which is very helpful in keeping our docs up to date with our product. Nothing worse than incorrect docs!

We use React components extensively, and I'm not really happy with our prop reference tables which use Palintir's Documentalist. Our components are increasingly using complex TypeScript generics to represent behaviour. The benefits in the IDE are huge, but the relatively dumb display of type information in the prop table leaves something to be desired. I'm most likely going to replace the data for those tables with compile-time generated Twoslash queries.

My only complaints have been around absolute speed of compilation, but I haven't dug deep into improving that. I just set up a per snippet caching layer, and once files are cached, individual changes are refreshed quickly. After all, it's invoking the full TypeScript compiler, and that's its biggest feature.

Overall I've been very happy with Twoslash, and I'm looking forward to refactoring to use this successor and Shikiji (the ESM successor to Shiki), hopefully it improves our performance. The new Twoslash docs are look great, a huge improvement on when we started using it.