Если ты пишешь документацию или туториалы с TypeScript-примерами, то знаешь боль: код в доках устаревает, типы врут, а читатель путается. Twoslash решает это через специальный формат разметки.
Что такое Twoslash
Twoslash — это система разметки кода, которая позволяет встраивать компилятор TypeScript прямо в процесс подготовки документации. Ты пишешь сниппет с особыми комментариями-аннотациями, а Twoslash прогоняет его через tsc, собирает информацию о типах и встраивает её в итоговый вывод.
Главная идея: примеры становятся самодостаточными — они не просто показывают код, но и несут актуальную типовую информацию, проверенную компилятором в момент сборки.
Зачем это нужно
- Воспроизводимость — каждый сниппет проходит реальную проверку типов, так что опечатки и устаревший API не проскочат незамеченными.
- Богатый вывод — можно показывать инферированные типы, ошибки компилятора, подсказки прямо в тексте документации.
- Интеграция — Twoslash используется в таких проектах, как официальная документация TypeScript и VitePress-сайты.
Как это выглядит
В коде ставишь специальные комментарии — например, // ^? под переменной, чтобы показать её инферированный тип:
const user = { name: "Alice", age: 30 };
// ^? const user: { name: string; age: number }
Twoslash разворачивает такую аннотацию в реальное значение, полученное от компилятора.
Для кого
Прежде всего для авторов технической документации, туториалов и блогов про TypeScript. Если хочется, чтобы примеры кода не врали читателю — 🦆 это именно тот инструмент, который стоит добавить в пайплайн.