Для своих задач я искал открытую библиотеку чата на актуальном стеке React Native, которую можно развивать, не подстраивая приложение под накопленные ограничения чужого API. Меня интересовал не только готовый интерфейс: хотелось разделить состояние и отображение переписки, а также взаимодействие с API. Поэтому было решено создать собственную библиотеку для работы с чатами – Talkentry. Цель проекта: обеспечить общение пользователей внутри приложений, решить поставленные задачи и сделать библиотеку открытой для интеграций и вклада сторонних разработчиков.
Это первая статья о проекте, и начнём мы с воспроизводимого локального запуска. Возьмём специально подготовленный пример, поднимем API, откроем чат на Android-телефоне и проверим отправку сообщения. После этого разберём основные компоненты и границу между SDK и реальным backend. Предполагается поверхностное знакомство с компонентами библиотеки и получение среды для дальнейшей разработки.
Что будем запускать
Talkentry состоит из общего ядра и платформенных UI-пакетов; здесь нас интересует @talkentry/react-native с готовым экраном, провайдером сессии и хуками.(Документация React Native-пакета) Сервер сообщений, авторизация и постоянное offline-хранилище не входят в SDK: приложение подключает backend через контракт ChatAdapter. (Описание SDK)
Чтобы первый запуск не начинался с реализации backend контракта, воспользуемся отдельным репозиторием talkentry-example: в нём уже есть Expo-приложение, reference adapter, NestJS API и конфигурация PostgreSQL. Пакеты SDK устанавливаются из npm, поэтому клонировать исходники самой библиотеки рядом с примером не требуется. (Инструкция запуска примера)
Нужные ссылки собраны здесь. Не путайте исходники SDK с запускаемым приложением-примером:
Библиотека: Talkentry на GitHub. Исходный код SDK.
Готовый пример: talkentry-example на GitHub.
Пакеты npm: @talkentry/react-native и общее ядро @talkentry/core; при установке native-пакета ядро приходит как зависимость. (Инструкция установки)
Подготовка проекта к локальному запуску
В примере зафиксированы Node.js 24.22.1 и npm 11; для базы данных нужен Docker с Compose. Для выбранного здесь маршрута также подготовьте Android SDK и среду локальной сборки, описанную в руководстве Expo. (Локальная разработка с Expo) Будем использовать физический Android-телефон с разрешенной USB-отладкой и доступом к компьютеру по локальной сети.
Клонируем проект и установим зависимости из корня репозитория. Если используете nvm, перед установкой выполните nvm install и nvm use: они прочитают версию из .nvmrc.
Если собираетесь изучать или менять сам SDK, отдельно скачайте его исходники командой: git clone https://github.com/Talkentry/talkentry.git Для приведённого запуска это необязательный шаг: пример использует пакеты из npm, а не соседний checkout библиотеки.
Дальше из того же корня запускаем PostgreSQL и API. Эти команды предусмотрены скриптами примера; сервер работает на порту 3087. Не забудьте создать файл .env в каталоге ./server перед запуском.
npm run docker:up
npm run server
Не закрывайте терминал с сервером. В другом терминале проверьте его доступность:
curl --fail http://127.0.0.1:3087/health
В ответе проверяйте не только доступность HTTP: рабочее состояние обозначается полями status: “ok” и services.postgres: true; при ошибке базы обработчик возвращает status: “critical”. Если проверка не проходит, сначала разберитесь с журналом API, Docker и server/.env, а уже затем переходите к React Native.
Это локальный учебный сервер без пользовательской аутентификации: оба демонстрационных клиента работают с фиксированным user-1. Не публикуйте его в интернете и не используйте реальные переписки. Для первого запуска достаточно доверенной локальной сети и тестовых данных.
Запускаем React Native-приложение
В примере уже зафиксированы Expo, React Native и native-зависимости, поэтому первый запуск не будем совмещать с их ручным подбором. Для существующего приложения совместимость придётся проверить отдельно по peer dependencies выбранной версии пакета. (Манифест SDK 0.0.1)
Для воспроизводимого native-окружения выберем собственную development build. Expo описывает этот режим как приложение со своим набором native-модулей; одна только работа Metro не означает, что установленный клиент содержит всё необходимое. (Development builds в Expo)
Из нового терминала, оставив API работающим, выполните:
cd talkentry-example/apps/mobile
npx expo install expo-dev-client
npx expo run:android --device
Последняя команда собирает приложение локально и позволяет выбрать устройство для установки. Для следующих запусков, пока native-зависимости не менялись, достаточно стартовать Metro:
npx expo start --dev-client
До разбора кода проверьте адрес API. В примере функция resolveTalkentryApiUrl() берёт адрес хоста из Expo и добавляет порт 3087; если адреса нет, она использует 10.0.2.2 на Android и localhost на остальных платформах. (Реализация определения адреса)

Откройте в браузере телефона http://<LAN_IP>:3087/health и проверьте те же поля состояния базы. Не подставляйте localhost и не считайте доступный Metro доказательством работоспособности API. Если запрос не проходит, проверьте общую сеть и firewall; при нестандартной сетевой схеме задайте доступный телефону baseUrl адаптера явно.
После установки откройте приложение и дождитесь истории. Затем отправьте сообщение с уникальным текстом, перезапустите приложение и найдите его снова: это отдельная проверка сохранения, а не только появления пузыря на экране.

Какие компоненты нужны для одного экрана
Полное демо содержит дополнительное оформление, обработчик копирования и выбор изображения; для текстового чата эти прикладные части можно временно убрать. (Исходный экран примера) Ниже минимальная версия, которой можно заменить apps/mobile/App.tsx внутри уже установленного проекта. Импорты адаптера и определения адреса остаются локальными: это файлы приложения-примера, а не скрытые экспорты npm-пакета.
import { Chat, TalkentryProvider } from '@talkentry/react-native';
import { KeyboardProvider } from 'react-native-keyboard-controller';
import {
SafeAreaProvider,
SafeAreaView,
} from 'react-native-safe-area-context';
import {
appendNativeUpload,
TalkentryServerAdapter,
} from '../../adapter/native';
import { resolveTalkentryApiUrl } from './apiUrl';
// Один экземпляр адаптера для этой демонстрационной сессии.
const adapter = new TalkentryServerAdapter({
baseUrl: resolveTalkentryApiUrl(),
appendUpload: appendNativeUpload,
});
export default function App() {
return (
<SafeAreaProvider>
<KeyboardProvider>
<SafeAreaView
style={{ flex: 1 }}
edges={['top', 'left', 'right']}
>
<TalkentryProvider
adapter={adapter}
chatId="demo"
currentUserId="user-1"
scopeKey="local-demo:user-1:session-1"
>
<Chat
locale="en"
messageListProps={{ isActive: true }}
/>
</TalkentryProvider>
</SafeAreaView>
</KeyboardProvider>
</SafeAreaProvider>
);
}
В минимальном варианте компоненты выполняют разные задачи. Не нужно параллельно заводить массив сообщений в React state и вручную создавать вторую сессию для того же экрана:
Chat: готовый интерфейс списка сообщений и поля ввода. (Native guide)
TalkentryProvider: связывает дочерние компоненты с сессией и переданным адаптером. (Подключение SDK)
KeyboardProvider и SafeAreaProvider: рекомендованные внешние обёртки для native-экрана. (Требования интеграции)
TalkentryServerAdapter: реализация транспорта из example-проекта; это не обязательный backend всей библиотеки. (Адаптер примера)
У провайдера три идентификатора с разным назначением: chatId выбирает переписку, currentUserId задаёт текущего пользователя, а scopeKey участвует в идентичности сессии и должен меняться при смене tenant или сеанса авторизации. Это не механизм авторизации и не замена серверной проверке доступа. В демо ключ фиксирован намеренно; в настоящем приложении свяжите его с жизненным циклом входа пользователя.
Экземпляр адаптера вынесен за компонент, чтобы оставаться стабильным между рендерами. Для приложения со сменой учётных записей выбирайте подходящий жизненный цикл, а не копируйте глобальный экземпляр без учёта авторизации.
isActive: true подходит для единственного открытого экрана; с навигацией передавайте реальную активность, чтобы скрытый чат не инициировал навигацию и прочтение. (Активность экрана) Локаль в примере оставлена en: именно она документирована в native API.
Что понадобится от реального backend
Провайдер не знает адресов вашего API и не превращает переданный currentUserId в подтверждённую identity: инфраструктура подключается через ChatAdapter. Для собственной интеграции стоит начать с такого разделения ответственности:
Приложение и адаптер: получить credentials, выполнить запросы и преобразовать ответы в контракт SDK.
Сервер: проверить пользователя и доступ к переписке, валидировать входные данные и сохранять сообщения.
История и события: согласовать пагинацию, идентификаторы, порядок обновлений и поведение после разрыва соединения.
Дополнительные функции: отдельно определить контракты вложений, прочтений и других возможностей, которые действительно нужны продукту.
Необязательно повторять NestJS, PostgreSQL и Socket.IO: это выбор reference-примера, а не обязательный стек SDK. (Server Adapter) Важно реализовать согласованный контракт, а не только вернуть подходящий JSON для первого экрана.

Как проходят история и отправка
При старте сессия запрашивает последнюю страницу через loadLatest и подключает subscribe; более ранние сообщения загружаются через loadBefore. (Контракт истории) В reference adapter запросы идут по HTTP, а события приходят через Socket.IO. (Реализация транспорта)
Отправка оптимистическая: строка появляется локально до серверного подтверждения. (Поведение SDK) Сервер сохраняет сообщение и публикует события, а сессия согласует HTTP-ответ и realtime-эхо, связывая локальную и серверную записи через идентификаторы. (Отправка на сервере, контракт SDK) Порядок их получения клиентом не стоит считать фиксированным; появившийся пузырь сам по себе не подтверждает сохранение.

После повторного соединения reference adapter передаёт history.invalidated, чтобы сессия не полагалась только на новые live-события. (Обработка reconnect) Ядро пытается восстановить состояние через журнал событий, если доступны курсор и loadEvents; иначе использует допустимую дозагрузку либо перезагрузку последней страницы. (Алгоритм восстановления) Это не обещание получить каждое пропущенное событие и не постоянная offline-очередь.

Для ручной проверки откройте второй клиент, например web-демо командой npm run web из корня репозитория. Оба штатных клиента используют user-1, поэтому такой тест проверяет обмен событиями между клиентами, а не авторизацию двух разных участников. Дополнительно проверьте подгрузку истории, возврат после отключения сети и поведение списка при открытии клавиатуры; не считайте эти сценарии пройденными только потому, что приложение собралось.
Что дальше
Talkentry только начинает развиваться: API ещё может меняться, а поведение на устройствах и готовность production-интеграции требуют отдельной приёмки. Наш следующий ориентир: расширять функциональность и улучшать существующие сценарии с учётом реальных интеграций, а не объявлять библиотеку законченной после первого демо.
Если встретите проблему, пожалуйста, создайте issue в репозитории Talkentry. Приложите версии пакетов, модель устройства и ОС, шаги воспроизведения, ожидаемый и фактический результат; по возможности добавьте минимальный пример без персональных данных и секретов. Особенно полезна обратная связь о первом запуске, поведении чата и том, насколько удобно подключать собственный backend.
Спасибо за интерес к проекту и за любой будущий вклад: отчёт об ошибке, уточнение документации, предложение или код. Надеюсь, этот пример поможет начать собственную интеграцию, а обсуждение сделает библиотеку полезнее для других разработчиков.

Комментарии 0