Как подключить typescript к react
Стартуем библиотеку компонентов на React и TypeScript
Большую часть свой работы, я пишу бэкенды, но вот на днях появилась задача начать библиотеку компонентов на React. Несколько лет назад, когда версия React была такой же маленькой, как и мой опыт фронтенд-разработки, я уже делал подход к снаряду и получилось неумело и коряво. Принимая во внимание зрелость текущей экосистемы React и мой подросший опыт, я воодушевился уж в этот-то раз сделать всё хорошо и удобно. В результате у меня появилась заготовка для будущей библиотеки, а чтобы ничего не забыть и собрать всё в одном месте, была написана эта статья-шпаргалка, которая также должна помочь тем, кто не знает, с чего начать. Посмотрим, что же у меня получилось.
TL/DR: Код готовой к старту библиотеки можно посмотреть на github
К задаче можно подойти с двух сторон:
Первый способ хорош для быстрого старта, когда вы совершенно не хотите разбираться с конфигурированием и подключением необходимых пакетов. Также этот вариант подойдёт для новичков, кто не знает с чего начать и в чём должно быть отличие бибилиотеки от обычного приложения.
Вначале я пошёл первым путём, но затем решил обновить зависимости и прикрутить ещё пару пакетов, и тут посыпались всякие ошибки и несостыковки. В итоге закатал рукава и сделал всё сам. Но генератор библиотек таки упомяну.
Create React Library
Большинство разработчиков, которые имели дело с React слышали про удобный стартер приложений на React, который позволяет свести конфигурацию проекта к минимуму и предоставляет разумные дефолты — Create React App (CRA). В принципе, его можно было бы использовать и для библиотеки (и есть статья на хабре). Однако, структура проекта и подход к разработке ui-kit немного отличается от обычного SPA. Нам нужен отдельный каталог с исходниками компонентов (src), песочница для их разработки и отладки (example), инструмент документирования и демонстрации («витрина») и отдельный каталог с подготовленными к экспорту файлами (dist). Также компоненты библиотеки не будут складываться в SPA приложение, а будут экспортироваться через индексный файл. Подумав об этом, я отправился на поиски и быстро обнаружил подобный CRA пакет — Creat React Library (CRL).
CRL, также как и CRA, является «easy-to-use» CLI-утилитой. С помощью неё можно сгенерировать проект. Он будет содержать:
Для генерации проекта библиотеки выполним(npx позволяет не устанавливать пакеты глобально):
И в результате работы утилиты получим сгенерированный и готовый к работе проект библиотеки компонентов.
На сегодняшний день зависимости немного устаревшие, поэтому я решил обновить их всех до последних версий с помощью npm-check:
Ещё одним печальным фактом является то, что приложение-песочница в каталоге example генерируется на js. Придётся руками переписать его на TypeScript, добавив tsconfig.json и некоторые зависимости (например, сам typescript и основные @types ).
Спасибо пользователю StanEgo, который рассказал про отличную альтернативу Create React Library — tsdx. Эта cli-утилита также похожа на CRA и в одну команду создат основу для вашей библиотеки с настроенным Rollup, TS, Prettier, husky, Jest и React. Причем React идёт как опция. Достаточно просто выполнить:
И в результате будут установлены необходимые свежие версии пактов и сделаны все настройки. Получим похожий на CRL проект. Основное отличие от CRL — Zero-config. Т. е. конфиг Rollup скрыт от нас в tsdx (также как это делает CRA).
Быстро пробежавшись по документации, я не нашёл рекомендуемых способов более тонкой конфигурации или что-то вроде eject как в CRA. Заглянув в issue проекта, обнаружил, что пока такой возможности нет. Для каких-нибудь проектов это может быть критично, в этом случае придётся немного поработать руками. Если же вам это не нужно, то tsdx отличный способ, чтобы быстро начать.
Берём управление в свои руки
Теперь установим пакеты react и react-dom и необходимые types (т.к. мы будем пилить компоненты на TypeScript) как devDependencies (как и все пакеты в этой статье):
Rollup
Для сборки будем использовать Rollup, как предлагал CRL. Необходимые пакеты и конфиг, я подсматривал также у CRL. Вообще слышал мнение, что Rollup хорош для библиотек, а Webpack для приложений. Однако, я не конфигурировал Webpack (мне хватало того, что делает за меня CRA), но Rollup действительно хорош, прост и красив.
В package.json добавим поля с распложением собранных бандлов библиотеки, как рекомендует нам rollup — pkg.module:
Конфиг представляет собой js-файл, а точнее экспортируемый объект. В поле input указываем файл, в котором прописаны экспорты для нашей библиотеки. output — описывает наши ожидания на выходе — в модуль какого формата скомпилировать и куда его положить.
Первый компонент и экспортный файл
Также в src надо создать файл с общими для библиотеками типами, где будет объявлен тип для css и svg (подсмотрено у CRL).
Далее добавим несколько инструментов для повышения качества нашего процесса разработки и его результата.
Забываем о форматировании кода с Prettier
Терпеть не могу в code-review указывать на небрежное или нестандартное для проекта форматирование, а тем более спорить про него. Подобные недочёты естественно должны быть исправлены, однако разработчикам лучше сосредоточиться на том, что и как код делает, а не как он выглядит. Эти исправления — первый кандидат на автоматизацию. Есть прекрасный пакет под эту задачу — prettier. Установим его:
Добавим конфиг для небольшого уточнения правил форматирования.
Мы можем не ждать форматирования до коммита, а сделать так, чтобы prettier постоянно срабатывал на изменённые файлы в процессе нашей работы. Да, нам нужен ещё один пакет — onchange. Он позволяет следить за изменениями файлов в проекте и тут же выполнять необходимую для них команду. Устанавливаем:
Затем в команды поля scripts в package.json добавляем:
На этом все споры о форматирвании в проекте можно считать закрытыми.
Избегаем ошибок с ESLint
ESLint уже давно стал стандартом и его можно встретить практически во всех js и ts-проектах. Нам он тоже поможет. В конфигурировании ESLint я доверяю CRA, поэтому просто возьмём необходимые пакеты из CRA и подключим в нашу библиотеку. Кроме того, добавим конфиги для TS и prettier (чтобы избежать конфликтов между ESLint и prettier ):
Настроим ESLint с помощью конфигурационного файла.
Тестируем с Jest
Чтобы писать модульные тесты для компонентов библиотеки, установим и сконфигурируем Jest — библиотеку тестирования от facebook. Однако, т.к. мы компилируем TS не через babel 7, а через tsc, то нам нужно также установить пакет ts-jest:
Чтобы jest нормально воспринимал импорты css или других файлов, необходимо подменить их моками. Создаём каталог __mocks__ и создаём там два файла.
styleMock.ts :
Теперь создаём конфиг jest.
Напишем простейший тест для нашего ExampleComponent в его каталоге.
Разрабатываем, документируем и любуемся компонентами с Storybook
Каждая библиотека нуждается в хорошей документации для её успешного и продуктивного использвания. Что касается библиотеки компонентов интерфейса, то про них не только хочется прочитать, но и посмотреть как они выглядят, а лучше всего потрогать и поизменять. Для поддержки такой хотелки есть несколько решений. Раньше я использовал Styleguidist. Этот пакет позволяет писать документацию в формате markdown, а также вставлять в неё примеры описываемых React-компонентов. Далее документация собирается и из неё получается сайт-витрина-каталог, где можно найти компонент, прочитать документацию о нём, узнать о его параметрах, а также потыкать в него палочкой.
Однако в этот раз я решил присмотреться к его конкуренту — Storybook. На сегодняшний момент он кажется более мощным с его системой плагинов. Кроме того, он постоянно развивается, имеет большое сообщество и скоро также начнёт генерировать свои страницы документации с помощью markdown-файлов. Ещё одно достоинство Storybook это то, что он является песочницей — средой для изолированной разработки компонентов. Это означает, что нам не нужны никакие полноценные приложения-примеры для разработки компонентов (как это предлагает CRL). В storybook мы пишем stories — ts-файлы, в которых мы передаём наши компоненты с некоторыми входыми props в специальные функции (лучше посмотреть на код, чтобы стало понятнее). В итоге из этих stories собирается приложение-витрина.
Запустим скрипт, который выполнит инициализацию storybook:
Теперь подружим его с TS. Для этого нам нужно ещё немного пакетов, а заодно поставим пару полезных аддонов:
Напишем нашу первую story в каталоге компонента ExampleComponent
Мы использовали аддоны:
Разрабатываем
Кроме того, можно авторизоваться в npm и опубликовать свою библиотеку как новый npm-пакет. А можно подключать её прямо из git-репозитория как из master, так и из других веток. Например, для моей заготовки можно выполнить:
Также, благодаря TS, будет работать автодополнение в IDE.
Подводим итоги
В середине 2019 года можно довольно быстро начать разрабатывать свою библиотеку компонентов на React и TypeScript, пользуясь удобными инструментами разработки. Этого результата можно достичь как с помощью автоматизированной утилиты, так и в ручном режиме. Второй путь является предпочтительным, если нужны актуальные пакеты и больше контроля. Главное знать куда копать, а с помощью примера в этой статье, я надюсь, это стало несколько проще.
Вы также можете взять получившуюся заготовку тут.
Кроме всего прочего, я не претендую на истину в последней инстанции и, вообще, занимаюсь фронтендом постольку-поскольку. Вы можете выбрать альтернативные пакеты и опции конфигурации и также достичь успеха в создании своей библиотеки компонентов. Буду рад, если вы поделитесь в комментариях своими рецептами. Happy coding!
Typescript + React. Быстрый старт.
Содержание
React
Итак, я думаю, что все знают о React ’е. Нет смысла рассказывать подробности, если вы не в курсе, что это за покемон — вряд-ли вам будет полезна эта статья. Но если вы все таки хотите ознакомиться со статьей — бегом читать доку и только после этого возвращаться к статье.
Typescript
Создание проекта
Итак, начать стоит с создания проекта. Для создания простого (ознакомительного) проекта на React+TS рекомендую воспользоваться тулой create-react-app с параметром:
Работа с компонентами
Этот простой компонент без использования typescript будет написан так:
И тут мы сразу же встречаем несколько проблем:
TS позволяет избегать простейших ошибок с типами данных, которые проходят через ваше приложение, а также позволяет структурировать и строго определять входные и выходные параметры ваших функций(читай Компонентов, сторов и всего остального)
Работа со стором
Далее следует простое объявление action creator’ов. Это простые функции, возвращающие экшены. Благодаря типизации( CounterAction ) мы придерживаемся одинакового вида всех action creator’ов.
И, наконец, редьюсер:
Работа с API
Преимущества TS
Если вы разрабатываете или собираетесь разрабатывать большой проект с длительной поддержкой — TS для вас must have Пусть он и не принесет много профита на старте, но спустя некоторое время рефакторить и разрабатывать приложение будет гораздо проще. Конечно, на TS тоже можно говнокодить, но делать это гораздо сложнее, поскольку сам язык регулярно бьет тебя по рукам и не дает писать плохой код. TS оградит вас от примитивных багов и ошибок и добавит вашему проекту уверенности. Но, не стоит забывать, что typescript помогает только на этапе разработки. После компиляции он полностью исчезает и в runtime работает старый-добрый JS со всеми его плюсами и минусами. Если вы гонитесь за качетсвом кода и имеете достаточное количество времени на изучение и внедрение технологии — Typescript ваш выбор!
Если вы решили использовать Typescript, но исключили из workflow юнит-тестирование — это очень плохой подход. Лучше всегда выбрать тесты, нежели Typescript, поскольку Typescript проверяет ваш код, а тесты проверяют бизнес-логику, что гораздо важнее!
Недостатки
Но, как мы все знаем, серебряной пули не существует и у TS также есть свои недостатки:
Заключение
TypeScript и React с использованием create-react-app: пошаговое руководство по настройке вашего первого приложения
Из этого туториала вы узнаете, как быстро приступить к созданию приложений React с использованием TypeScript без необходимости какой-либо настройки с помощью create-react-app (CRA). Предположим, что на вашем компьютере уже установлены Node и NPM. Ваше приложение TypeScript/React будет работать сразу после установки без необходимости использовать CRA. Кроме того, вы узнаете, как создавать свои собственные компоненты и управлять props и state, используя TypeScript.
Установка с помощью create-react-app
create-react-app это инструмент командной строки, который позволяет разработчикам легко создавать новые приложения React с разумными настройками по умолчанию и нулевой конфигурацией.
Примечание. Этот шаг теперь необязательный. TypeScript можно установить с помощью npx, который будет показан в следующем разделе.
Инициализируйте свое приложение React с помощью TypeScript
Вызовите команду create-react-app с дополнительной опцией TypeScript, чтобы сгенерировать приложение React с использованием TypeScript в качестве синтаксиса JS по умолчанию.
Это создаст следующие файлы и структуру папок:
Ниже описание каждой части:
Изменения React под TypeScript
Чтобы использовать React с TypeScript, вы должны внести небольшие изменения в подходе создания стандартного приложения React.
Импорт React и ReactDOM
Вы можете заметить, что в компонентах по умолчанию используется следующий синтаксис:
С TypeScript вы больше не сможете делать стандартные импорты фида:
React экспортируется как модуль CommonJS, который не использует default export. На данный момент, не обязательно точно знать, почему, а просто знать, как вы должны импортировать React, чтобы он работал. Это также означает, что вы объявляете свои компоненты как:
Создание компонент
Вы определите интерфейс props для каждого из компонентов, которым вы передаете параметры. Вы определяете интерфейс объекта и где у каждого ключа может быть свой тип данных. Кроме того, вы можете объявить интерфейс для состояния (state) компоненты.
Функциональный компонент без хранения состояния
Чтобы продемонстрировать функциональный компонент с props, мы заменим заголовок
Начнем с импорта React. Затем мы объявляем интерфейс IProps с единственным параметром name. Мы указали что параметр необязательный, это задается симфолом “?”. Обозначение ключа как необязательного означает, что входной параметр может быть или string или undefined.
При создании компоненты Header, обратите внимание на React.SFC
. «SFC» обозначает функциональный компонент без сохранения состояния в прототип. Хотя это объявление не является обязательным, оно позволяет нам использовать defaultProps.
Далее, мы объявляем тип входного параметра как IProps, ссылающийся на созданный нами интерфейс.
Компонент класса
Чтобы показать основы компонента класса, мы заменим описание
в App.tsx на счетчик. Одним из ключевых различий между классом и функциональным компонентом является то, что компонент класса может поддерживать свое собственное состояние. Другим основным отличием является возможность доступа к методам жизненного цикла, описание которых выходит за рамки данного руководства.
Мы начнем с объявления интерфейса для IProps и IState. Будет необязательный счетчик вызовов счетчика, который будет определять значение приращения. Сам компонент будет вести подсчет, используя свое состояние.
Компонент объявлен с типами IProps и IState как class Description extends React.Component < и defaultProps объявлен как статическая переменная. State инициализируется со счетчиком 0.
Ваше create-react-app с компонентами TypeScript
Внутри нашего App.tsx мы импортируем только что созданные компоненты и заменяем HTML по умолчанию из CRA. Параметры name и countBy должны соответствовать типам, объявленным в дочернем компоненте. Поскольку props являются необязательными, они также могут быть undefined, и будет использоваться defaultProps.
И это все, что вам нужно для начала работы с TypeScript в React! Чтобы увидеть, как работает ваше приложение запустите следующую команду в консоли:
Работа с React и TypeScript
Мы собираемся разработать знаменитое TODO приложение из проекта TodoMVC с помощью React и TypeScript:
В этом посте будет проделано следующее:
Настройка среды
Этот плагин обладает некоторыми интересными функциями, например, конвертирование HTML в JSX:
Или отображение вида зависимостей:
Зайдите на страницу проекта на GitHub, чтобы узнать больше о возможностях atom-typescript.
Установите инструменты разработчика для работы с React для Хрома. Это расширение пригодится нам для отладки React-приложений путем отображения значений свойств и состояния выбранного компонента.
Создание проекта
К концу этого учебника структура проекта будет такой:
Давайте начнем с создания корневой папки приложения.
Затем создайте новый файл package.json в корневой папке приложения:
После этого вы можете установить зависимости проекта с помощью npm:
Эта команда создаст папку с именем node_modules внутри корневой папки приложения. node_modules должен содержать 3 папки: directorem, react и todomvc-app-css.
Теперь мы установим некоторые файлы-определители типов TypeScript. Такие файлы исользуются для объявления интерфейсов публичных API сторонних таких библиотек, как React. Такие интерфейсы могут использоваться в IDE для развития приложений TypeScript с такими функциями как IntelliSense.
Файлы-определители типа также используются компилятором TypeScript для гарантии, что мы используем сторонние библиотеки правильно.
Мы будем нуждаться в файлах-определителях типов. Мы можем установить их с помощью следующей команды:
Команда выше создаст файл с именем tsd.json и папку с именем typings в корневой папке приложения. Папка typings должна содержать папку по имени react.
Нам также необходимо вручную скачать и сохранить файл с именем react-global.d.ts под папкой typings/react.
Теперь, давайте создадим файл index.html внутри корневой папки приложения:
На этом этапе вы должны иметь следующие файлы и папки:
Вы можете заметить, что некоторые из JavaScript файлов, на которые ссылается наш файл index.html отсутствуют. Теперь мы перейдем к решению этой проблемы.
Базовый экскурс в React-компоненты
Компонент TodoApp будет состоять из нескольких компонентов, в том числе одного компонента TodoFooter и списка компонентов TodoItem.
Компоненты отличать два различных набора данных: свойства и состояние.
Свойства
Компонент не может изменить свои свойства, но отвечает за соединение свойств дочерних Компонентов.
Состояние
Состояние имеет значение по умолчанию при установке компонента, а затем зависит от изменений (в основном генерируется из пользовательских событий). Это сериализуемое представление одного момента времени – снэпшот.
Компонент сам управляет своим состоянием, но, помимо установки начального состояния, не изменяет состояние дочерних компонентов. Можно сказать, что его состояние приватно.
Когда мы объявляем новый React компонент с помощью машинописи мы должны объявить интерфейс свойств и состояния так:
Теперь, когда мы сформировали структуру проекта и изучили основы о компонентах, пришло время начать разработку компонентов.
Резработка React-компонентов с помощью TypeScript
Давайте создадим новую папку с именем js в корневой папке приложения. Мы собираемся создать в ней следующие файлы:
Вы можете создать их сейчас или по мере необходимости и применения каждого из них.
interfaces.d.ts
Мы будем использовать этот файл, чтобы определить все интерфейсы в вашем приложении. Мы используем расширение .d.ts (который также используется файлами-определителями типа) вместо .ts, поскольку эти файлы не будут транспилированы в файл JavaScript. Файл не транспилируется, поскольку интерфейсы TypeScript не переделываются в JavaScript-код в процессе компиляции.
constants.ts
Этот файл используется, чтобы определить некоторые константы. Константы используются для хранения числового значения клавиш клавиатуры (ENTER_KEY и ESCAPE_KEY), которые мы будем использовать позже, чтобы установить некоторые слушатели событий. Мы также будем использовать некоторые значения, чтобы определить текущий отображаемый список задач по его статусу:
utils.ts
todoModel.ts
TodoModel – это общий объект моделей. Приложение имеет весьма маленький объем, поэтому не имеет смысла даже выносить логику отдельно,
footer.tsx
Этот файл использует расширение .tsx вместо расширения .ts, потому что он содержит TSX код.
TSX – это набор JSX. Мы будем его использовать вместо HTML клиентских шаблонов как Handlebars, поскольку TSX и JSX используются для создания внутреннего представления DOM. Когда состояние компонентов или свойства меняются, React рассчитывает наиболее эффективный способ обновления внутреннего представления DOM, а затем применяет эти изменения к настоящему DOM’у. Этот процесс делает React весьма эффективным, когда речь идет об управлении DOM’ом.
Нам необходимо использовать некоторые дополнительные опции компилятора для компиляции .tsx. Мы узнаем больше об этой теме в конце статьи.
Компонент footer (нижний колонтитул) позволяет фильтровать списки задач по их статусу и отображает количество задач. У этого компонента нет состояния (обратите внимание на то, как <> передались к React.Component в качестве интерфейса состояния), но есть некоторые свойства (ITodoFooterProps), которые заданы родительским компонентом (TodoApp).
todoItem.tsx
Компонент TodoItem представляет собой одну из задач в списке задач. Он имеет свойство ITodoItemProps и состояние ITodoItemState.
Начальное состояние компонента установлено в конструкторе компонента само собой в то время как свойства передаются в качестве аргументов и устанавливаются родительским компонентом (TodoApp).
app.tsx
Этот файл содержит точку входа приложения и объявление компонента TodoApp, который является единственным компонентом верхнего уровня в этом приложении.
Убедитесь, что оператор this все время указывает на правильный элемент. Например, вы должны использовать функции со стрелками:
чтобы убедиться, что оператор this указывает на компонент внутри функции handleNewTodoKeyDown.
Компиляция Приложения
Для компиляции нашего приложения необходимо добавить в папку js файл tsconfig.json:
Если мы проверим Опции компилирования на TypeScript то сможем узнать, как работать с файлом tsconfig.json file:
Приложение можно скомпилировать с помощью следующей команды:
Это создаст следующие JavaScript-файлы в папке js:
Вот файлы, к которым мы ссылались в файле index.html:
Теперь мы готовы запустить приложение.
Запуск приложения
Мы можем установить этот пакет с помощью следующей команды:
Используйте следующую команду для запуска приложения:
Если вы откроете браузер и перейдете на http://127.0.0.1:8080/, вы сможете увидеть работу приложения:
Не забывайте, что в Хроме можно посмотреть расширение с инструментами для разработчиков на React, а также то, как изменяются значения свойств и состояния компонентов при работе с приложением.
Выводы
В этой статье мы узнали как подготовить среду разработки и создать новый проект для работы с TypeScript и React. Теперь попробуйте сделать что-то свое)