Разработка кастомных компонентов 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