Розробка кастомних компонентів Retool під ключ

Часто стикаємося з ситуацією, коли вбудовані віджети Retool не справляються: потрібно відобразити 10k+ точок на карті з динамічною кластеризацією, а штатний Map-віджет гальмує вже на 500 точках. Або потрібна діаграма з нестандартною анімацією, drag-and-drop сортування з бізнес-правилами, Kanban-дошка з обмеженням WIP. Для таких завдань Retool надає механізм Custom Components — повноцінні React-застосунки, ізольовані в iframe та пов'язані з хостом через postMessage API. Ми побудували понад 50 таких компонентів під ключ для різних бізнес-задач, і накопичили практику, якою ділимося.

Як працюють кастомні компоненти? — розробка кастомних компонентів

Custom Component — це React-застосунок, який спілкується з Retool через бібліотеку @tryretool/custom-component-support. Вона надає React-хуки для синхронізації стану: Retool.useStateValue для читання/запису моделі та Retool.useEventCallback для відправки подій назад до Retool. Середовище розробки — локальний сервер (Vite або CRA), а готова збірка деплоїться на будь-який статичний хостинг.

// src/index.tsx — точка входу кастомного компонента import { Retool } from '@tryretool/custom-component-support'; interface ModelData { items: Array<{ id: string; label: string; value: number; color: string }>; selectedId: string | null; } export const BubbleChart: FC = () => { const [items] = Retool.useStateValue<ModelData['items']>({ name: 'items', initialValue: [], label: 'Chart items', inspector: 'array', }); const [selectedId, setSelectedId] = Retool.useStateValue<string | null>({ name: 'selectedId', initialValue: null, label: 'Selected item ID', inspector: 'string', }); const onSelect = Retool.useEventCallback({ name: 'onItemSelect' }); const handleBubbleClick = (id: string) => { setSelectedId(id); onSelect({ id }); }; return ( <BubbleChartRenderer items={items} selectedId={selectedId} onSelect={onSelect} /> ); }; 

Чому custom components краще вбудованих віджетів?

Вбудовані віджети покривають 80% типових завдань, але для 20% потрібне кастомне рішення. Порівняйте:

Для рідкісних форматів (chord diagram, force-directed graph) кастомний компонент — єдиний спосіб.

Типові завдання

Візуалізації: D3.js-графіки (chord diagram, force-directed graph, sankey), ECharts з кастомними серіями, Three.js-попередній перегляд 3D-моделей.

Інтерактивні таблиці: віртуалізовані списки через @tanstack/virtual для 50k+ рядків, inline-редагування з кастомними валідаторами, drag-and-drop сортування через @dnd-kit/core.

Карти: Mapbox GL JS / Leaflet з динамічними кластерами, drawing-інструменти для геозон, ізохрони через Mapbox Isochrone API.

Специфічні UI-патерни: Kanban-дошка з бізнес-обмеженнями, часова шкала Gantt, code editor на базі Monaco.

Що входить в роботу?

Ми розробляємо компонент під ключ: від проектування data contract до деплою та документації. В рамках задачі:

• Узгодження моделі даних і подій.
• Реалізація рендеру та всієї бізнес-логіки.
• Інтеграція з вашим Retool-оточенням (cloud або self-hosted).
• Оптимізація продуктивності (віртуалізація, lazy loading, мемоізація).
• Деплой на CDN або в Retool Toolbox.
• Документація з встановлення та використання.
• Навчання та письмова підтримка протягом 2 тижнів після здачі.

Збірка та деплой

Компонент збирається в єдиний бандл і деплоїться на статику. Retool підтримує два способи підключення: через URL (CDN/S3/Vercel) та через Retool Toolbox для self-hosted інстансів.

// vite.config.ts import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], build: { lib: { entry: 'src/index.tsx', name: 'RetoolCustomComponent', fileName: 'index', formats: ['umd'], }, rollupOptions: { external: ['react', 'react-dom'], output: { globals: { react: 'React', 'react-dom': 'ReactDOM', }, }, }, }, }); 

Після vite build — dist/index.umd.js завантажується в CDN або Retool Cloud Storage. В інтерфейсі Retool створюється Custom Component, вказується URL бандла та iframe-URL сторінки.

Передача складних даних

Retool обмежує модель даних серіалізованими типами. Для складних структур (вкладені об'єкти, файли) використовується JSON-серіалізація всередині рядкового поля:

const [rawConfig] = Retool.useStateValue<string>({ name: 'config', initialValue: '{}', label: 'JSON Config', inspector: 'text', }); const config = useMemo(() => { try { return JSON.parse(rawConfig); } catch { return {}; } }, [rawConfig]); 

Для великих датасетів (тисячі рядків) дані проброшуються через Retool Query, яка повертає JSON — компонент отримує їх напряму без дублювання стану в model.

Як створити кастомний компонент: 5 кроків

1. Налаштування проекту: створіть React-застосунок з Vite або CRA, встановіть @tryretool/custom-component-support.
2. Визначте data contract: узгодьте з замовником поля моделі (entries, properties) та події (callbacks).
3. Реалізуйте рендер та логіку: використовуйте хуки useStateValue для читання даних і useEventCallback для відправки подій.
4. Зберіть бандл: виконайте vite build з конфігурацією UMD.
5. Задеплойте: завантажте бандл на CDN або в Retool Toolbox та вкажіть URL в інтерфейсі Retool.

https://cdn.example.com/retool-components/bubble-chart/index.umd.js