Зекономити час на фронтенд-розробці з Orval

User is familiar with frontend development, working with ReactJS, Typescript, and React Query.Для фронтенд-розробників (Frontend Developers) важливим завданням, крім розробки UI, є інтеграція з API. Це займає понад 30% загального обсягу роботи в проектах. Тепер ви можете автоматизувати інтеграцію з API за допомогою Orval...

Мій технічний стек для фронтенд-проекту включатиме ReactJS, Typescript та React Query.

Основні задачі при інтеграції з API включають:

• Створення типів (types) для request, response та інших об'єктів API в Typescript.
• Написання функцій клієнта API (API call functions).
• Якщо ви використовуєте React Query, необхідно написати React Query hooks для кожного API.
• Синхронізація з фронтендом кожного разу, коли відбуваються зміни в бекенд API.

Orval Restful Client Generator (Source: https://orval.dev/)

Orval

Orval — це інструмент, що використовує стандарт OpenAPI (також відомий як Swagger) для автоматичного створення RESTful клієнтських функцій, React Query hooks та відповідних типів (types) для request, response та інших об'єктів.

Основні переваги використання Orval

• Підвищення продуктивності — завдяки автоматичному створенню практично всіх етапів інтеграції з API, ваша продуктивність суттєво зросте.
• Легкість у підтримці — щоразу, коли відбуваються зміни в API, можна знову запустити Orval, щоб синхронізувати ці зміни з фронтендом.
• Мінімізація помилок — автоматичне створення типів (type safety) для request, response та інших об'єктів API значно знижує ймовірність помилок у порівнянні з ручним написанням.
• Легка інтеграція з React Query — Orval автоматично генерує React Query hooks, що спрощує їх використання в проекті.

Тестування

Для прикладу я вирішив використати Orval для створення простого сайту для виконання операцій CRUD (створення, читання, оновлення, видалення) із задачами, і підготував зразкові проекти:

• orval-example-backend — Task CRUD API

Orval Example Backend

• orval-example-frontend — статичний сайт для списку задач, створення, оновлення та видалення

Orval Example Frontend

Щоб інтегрувати статичний фронтенд з API, ми виконаємо наступні кроки:

• Налаштуємо Orval.
• Використаємо Orval для автоматичного генерування.
• Застосуємо генеровані React Query hooks у UI.

Кроки документації з кожною зміною можна побачити в PR на orval-example-frontend

Крок 1. Встановлення Orval

npm install orval — save-dev

Крок 2. Встановлення React Query

npm install @tanstack/react-query

Крок 3. Налаштування Orval

У кореневій папці проекту створіть файл orval.config.ts і вставте наступні налаштування.

• input.target — вказує шлях до JSON, YAML файлу або URL-адреси OpenAPI документації.
• output.mode — вказує один з режимів: single, split, tags, tags-split. Якщо вибрати tags-split, то API буде розділено на основі тегів.
• output.target — вказує місце для збереження згенерованих файлів.
• output.schemas — вказує шлях для збереження моделей.
• output.client — вибір типу клієнта, наприклад, angular, axios, react-query, vue-query, swr тощо. Якщо вибрати react-query, то Orval згенерує React Query hooks.
• output.override — дозволяє змінити параметри генерації.
  axios instance або інший React Query hook можна переписати за допомогою override._

Якщо ви хочете дізнатися більше про конфігурацію orval, натисніть тут.

Крок 4. Генерація за допомогою Orval

npx orval

Крок 5. Додавання клієнта React Query

У файлі main.tsx додайте клієнт React Query таким чином. Це дозволить використовувати React Query hooks у проекті.

Крок 6. Інтеграція Task списку з API

Для виклику React Query hook, який отримує список задач, використовуємо наступний код. Це всього одна строка.

const { data } = useTasksControllerGetTasks();

Отримані дані передаємо в таблицю, і основне завдання виконано.

Крок 7. Інтеграція Task CUD (create, update, delete) з API

Наприкінці

Orval — це дуже корисний інструмент для розробників, які працюють з ReactJS, React Query, Typescript для фронтенд-розробки. Автоматична генерація API клієнта та React Query hooks допоможе заощадити час, знизити ймовірність помилок і зберегти чистоту (clean) коду. Якщо ви ще не спробували Orval, обов'язково спробуйте в наступному проекті! 🙂

Перекладено з: Orval ашиглан фронтенд хөгжүүлэлтийн цагаа хэмнэх нь