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