@microsoft/api-extractor
Меня раздражают почти все потребительские продукты Microsoft, но то, что они делают для разработчиков, действительно воодушевляет.
Среди ассортимента крутых тулзов от них имеется api-extractor — утилита, которая, как следует из названия, "извлекает API" вашей библиотеки.
Под этим "извлечением" подразумевается сбор типов и комментариев в коде (для которых, кстати, разработана спецификация tsdoc) и формализация их в виде модели API библиотеки.
Возможно, звучит довольно скучно, но на практике эта модель позволяет без дополнительных телодвжений:
— упаковывать все
— валидировать публичный API библиотеки и централизованно следить за его изменениями, чтобы по более явным критериям определять наличие "breaking changes" при очередном релизе (с помощью автоматически генерируемого файла
— автоматически генерировать документацию по библиотеке (с помощью api-documenter);
— придумайте свой юзкейс.
Этот инструментарий уже зарекомендовал себя в опенсорс разработке и используется, например, в redux-toolkit.
#docs #tools #build
Меня раздражают почти все потребительские продукты Microsoft, но то, что они делают для разработчиков, действительно воодушевляет.
Среди ассортимента крутых тулзов от них имеется api-extractor — утилита, которая, как следует из названия, "извлекает API" вашей библиотеки.
Под этим "извлечением" подразумевается сбор типов и комментариев в коде (для которых, кстати, разработана спецификация tsdoc) и формализация их в виде модели API библиотеки.
Возможно, звучит довольно скучно, но на практике эта модель позволяет без дополнительных телодвжений:
— упаковывать все
*.d.ts файлы в один общий index.d.ts со всеми экспортируемыми типами;— валидировать публичный API библиотеки и централизованно следить за его изменениями, чтобы по более явным критериям определять наличие "breaking changes" при очередном релизе (с помощью автоматически генерируемого файла
api-report.md, который попадает в пулл реквесты и тоже становится предметом обсуждения);— автоматически генерировать документацию по библиотеке (с помощью api-documenter);
— придумайте свой юзкейс.
Этот инструментарий уже зарекомендовал себя в опенсорс разработке и используется, например, в redux-toolkit.
#docs #tools #build
В предыдущем посте была картинка с предлагаемым мной пайплайном для сборки библиотеки и первым этапом в нём является tsc — это компилятор тайпскрипта, который есть в самом пакете
Вероятно кто-то для сборки библиотеки решит взять Rollup или что-то подобное и накрутить гору плагинов, но на мой взгляд в подавляющем большинстве случаев это не будет иметь смысла и не принесёт ничего кроме усложнения сборки.
Единственное, чем может быть в данном случае полезен бандлер, — подключение не джаваскриптовых модулей. Например, для svg в react может понадобиться подключить svgr, но и у этого инструмента есть CLI, то есть его можно использовать и без бандлера. Не нужно использовать бандлер как таск-раннер. Кстати, я сейчас занимаюсь разработкой "умного" таск-раннера, который будет автоматически параллелить выполнение NPM-скриптов, так что ждите анонс.
Будет гораздо лучше доставить код до пользователя в максимально близком к исходному виде, чтобы уже пользователь библиотеки применял при необходимости какие-то свои оптимизации к модулям и добавлял полифиллы для новых возможностей языка, сохранив возможность использовать современный синтаксис.
Если скорость сборки с
В будущих постах расскажу ещё о нескольких инструментах и практиках сборки библиотек с помощью
#build #tools
typescript.Вероятно кто-то для сборки библиотеки решит взять Rollup или что-то подобное и накрутить гору плагинов, но на мой взгляд в подавляющем большинстве случаев это не будет иметь смысла и не принесёт ничего кроме усложнения сборки.
Rollup в отличии от tsc это бандлер — утилита, которая объединяет множество модулей в один файл (бандл). Но действительно ли это может быть полезно для библиотеки? На мой взгляд нет.Единственное, чем может быть в данном случае полезен бандлер, — подключение не джаваскриптовых модулей. Например, для svg в react может понадобиться подключить svgr, но и у этого инструмента есть CLI, то есть его можно использовать и без бандлера. Не нужно использовать бандлер как таск-раннер. Кстати, я сейчас занимаюсь разработкой "умного" таск-раннера, который будет автоматически параллелить выполнение NPM-скриптов, так что ждите анонс.
Будет гораздо лучше доставить код до пользователя в максимально близком к исходному виде, чтобы уже пользователь библиотеки применял при необходимости какие-то свои оптимизации к модулям и добавлял полифиллы для новых возможностей языка, сохранив возможность использовать современный синтаксис.
Если скорость сборки с
tsc вас не устраивает, можно просто заменить его на swc, но стоит учитывать, что tsc это на текщий момент единственный инструмент в экосистеме JavaScript, который умеет проверять типы (хотя вроде бы работа в этом направлении уже ведётся), остальные же просто их вырезают.В будущих постах расскажу ещё о нескольких инструментах и практиках сборки библиотек с помощью
tsc.#build #tools
One more thing!
В пайплайне сборки проекта помимо запуска
Для решения этой задачи я написал утилиту @lndsld/orc, которая сама запустит скрипты в нужной последовательности и распараллелит их, если это возможно. Для этого достаточно просто указать зависимости между скриптами прямо в
На текущий момент утилита имеет только самую базовую функциональность по оркестрации скриптов, но в будущем может стать более "умной", так что буду ждать вашего фидбэка :)
#tools #build
В пайплайне сборки проекта помимо запуска
tsc могут быть и другие утилиты (например, api-extractor), в таком случае просто запустить все скрипты параллельно не получится, так как необходимо соблюдать порядок их запуска (api-extractor должен быть запущен только после генерации .d.ts файлов).Для решения этой задачи я написал утилиту @lndsld/orc, которая сама запустит скрипты в нужной последовательности и распараллелит их, если это возможно. Для этого достаточно просто указать зависимости между скриптами прямо в
package.json.На текущий момент утилита имеет только самую базовую функциональность по оркестрации скриптов, но в будущем может стать более "умной", так что буду ждать вашего фидбэка :)
#tools #build
Релиз Rspack
Вчера вышла первая версия Rspack — бандлера, написанного на Rust, но с API, полностью совместимым с Webpack (ну пока что не полностью).
На бумаге это должно работать так: мы просто выкидываем Webpack из проекта, заменяем его на Rspack и получаем х10 скорость сборки.
На практике же всё пока не так радужно: я попробовал сделать такую замену в реальном проекте и получил кучу абсолютно нечитаемых исключений, выкинутых из Rust, поэтому я нашёл у себя маленький проект, в котором был простой Webpack-конфиг и попробовал сделать замену там, на сей раз успешно. Весьма нерепрезентативные результаты моих экспериментов в разных комбинациях вы можете видеть на приложенной картинке.
Помимо заявленной совместимости с Webpack Rspack предлагает также некоторое количество инструментов из коробки: например, самого быстрого результата удалось достичь без использования каких-либо лоадеров для Typescript-файлов, так как в Rspack уже встроен SWC.
Этот релиз — ещё один большой шаг к глобальной "растификации" Javascript-экосистемы. Предыдущим похожим проектом был Turbopack, но, несмотря на схожесть названия, он не предлагал такого простого способа для миграции с Webpack.
Посмотрим, во что в результате выльется такой проект. А он точно будет развиваться, поскольку разрабатывают его не опенсорс-энтузиасты, а небезызвестная компания ByteDance.
#tools #build
Вчера вышла первая версия Rspack — бандлера, написанного на Rust, но с API, полностью совместимым с Webpack (ну пока что не полностью).
На бумаге это должно работать так: мы просто выкидываем Webpack из проекта, заменяем его на Rspack и получаем х10 скорость сборки.
На практике же всё пока не так радужно: я попробовал сделать такую замену в реальном проекте и получил кучу абсолютно нечитаемых исключений, выкинутых из Rust, поэтому я нашёл у себя маленький проект, в котором был простой Webpack-конфиг и попробовал сделать замену там, на сей раз успешно. Весьма нерепрезентативные результаты моих экспериментов в разных комбинациях вы можете видеть на приложенной картинке.
Помимо заявленной совместимости с Webpack Rspack предлагает также некоторое количество инструментов из коробки: например, самого быстрого результата удалось достичь без использования каких-либо лоадеров для Typescript-файлов, так как в Rspack уже встроен SWC.
Этот релиз — ещё один большой шаг к глобальной "растификации" Javascript-экосистемы. Предыдущим похожим проектом был Turbopack, но, несмотря на схожесть названия, он не предлагал такого простого способа для миграции с Webpack.
Посмотрим, во что в результате выльется такой проект. А он точно будет развиваться, поскольку разрабатывают его не опенсорс-энтузиасты, а небезызвестная компания ByteDance.
#tools #build