Розробка користувацьких компонентів Retool
Retool охоплює більшість завдань внутрішніх інструментів вбудованими віджетами. Однак рано чи пізно виникає вимога, для якої немає готового компонента: специфічна візуалізація даних, інтерактивна карта з користувацькими маркерами, складний drag-and-drop з бізнес-логікою. Для цього Retool надає механізм Custom Components — ізольовані iframe React-додатки, вбудовані в інтерфейс через postMessage API.
Як працює механізм Custom Components
Користувацький компонент у Retool — це повнофункціональний React-додаток, який живе у ізольованому iframe. Взаємодія з хостом будується через Retool.useStateValue та Retool.useEventCallback. Дані передаються з Retool у компонент через model, компонент відправляє події назад через triggerQuery або довільні event-callback'и.
Середовище розробки — локальний сервер (Vite або CRA), код розгортається на будь-якому статичному хостингу або завантажується безпосередньо в Retool.
Структура компонента
// 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={handleBubbleClick}
/>
);
};
Пакет @tryretool/custom-component-support — обов'язкова залежність. Він абстрагує postMessage і надає React-hook'и для синхронізації стану.
Збірка та розгортання
Компонент збирається в один бандл і розгортається на статичний хостинг. 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 — компонент отримує їх безпосередньо без дублювання стану в моделі.
Типові завдання для користувацьких компонентів
Візуалізації: D3.js графіки (chord diagram, force-directed graph, sankey), ECharts з користувацькими рядами, Three.js попередні перегляди 3D-моделей.
Інтерактивні таблиці: віртуалізовані списки через @tanstack/virtual для 50k+ рядків, вбудоване редагування з користувацькими валідаторами, drag-and-drop сортування через @dnd-kit/core.
Карти: Mapbox GL JS / Leaflet з динамічними кластерами, інструменти малювання для геозон, ізохрони через Mapbox Isochrone API.
Специфічні UI-паттерни: Kanban-дошка з бізнес-обмеженнями, шкала часу Gantt, редактор коду на основі Monaco.
Що відбувається під час розробки
День 1–2: налаштування проекту (Vite + React + TypeScript + Retool SDK), домовленість про data contract — які поля в моделі, які події виводити. Мінімальний робочий компонент з mock-даними.
День 3–4: реалізація логіки та рендерингу. Паралельно — тестування інтеграції з реальним середовищем Retool (cloud або self-hosted — має значення, версії SDK відрізняються).
День 5: обробка граничних випадків, завантаження даних, стилізація відповідно до системи дизайну клієнта, розгортання в CDN, передача компонента з документацією.
Компонент середньої складності (користувацький графік або інтерактивна карта без складної логіки) — 3–5 днів. Kanban або Gantt з drag-and-drop та персистентністю — 1–2 тижні.