tyto.chat Client

Standalone React SPA for the tyto.chat platform. Consumes the core backend API and connects to Mercure for real-time message delivery.

This document will be most useful for developers working on the codebase. If you just want to install and run your own Tyto server, tyto.chat has you covered — see below.

Screenshots

The same build is responsive down to phone width:

More on tyto.chat/features; every screen is documented under tyto.chat/docs.

Running Tyto in production

Production runs the prebuilt client image alongside core via Docker Compose; the app is configured at runtime through container env (no rebuild). Follow the Quick Start; operational guides are in the documentation.

Development setup

Tech stack

• React 19 + TypeScript
• Vite 7 — dev server and bundler
• TanStack Router v1 — file-based routing
• TanStack Query v5 — server state management
• Tailwind CSS v4
• Tiptap — rich text message editor

Requirements

• DDEV v1.24+
• Docker
• A running core instance

Node.js is provided by DDEV — no local installation needed.

Setup

# 1. Clone the repository into a directory named "client"
git clone https://github.com/tyto-chat/client.git client
cd client

# 2. Start DDEV (installs Node dependencies automatically on first run)
ddev start

The app is now available at https://client.ddev.site.

Optionally, run ddev setup to configure .env.local and install the Playwright browser for E2E tests.

The project name is derived from the directory name. Clone into client to match the URLs above and to ensure the Mercure CORS configuration in core allows this origin.

The Chromium browser for Playwright is downloaded once and cached in .playwright-cache/ — subsequent ddev start calls skip the download.

Useful commands

Testing

Unit tests (Vitest)

Unit tests live in tests/unit/ and run entirely in-process — no browser or running backend needed.

ddev npm test              # run once
ddev npm run test:watch    # watch mode
ddev npm run test:coverage # with coverage report
ddev npm run test:ui       # Vitest browser UI

E2E tests (Playwright)

End-to-end tests in tests/e2e/ drive a real Chromium browser against the live DDEV stack. Both this client and the core backend must be running, and ddev setup must have been run at least once.

ddev e2e                       # reset core test DB, then run headless (default)
ddev npm run test:e2e:headed   # watch the browser (no DB reset)
ddev npm run test:e2e:ui       # Playwright interactive UI (no DB reset)

Each run:

1. Resets the core test database to a clean fixture state (the bootstrap admin).
2. Each Playwright worker seeds its own isolated world on demand — a community (e2e-w{n}) with a text and an audio channel, plus three role accounts (global admin, a regular member, and a community admin). Workers never share mutable state, so specs run fully in parallel.
3. Authenticates each role by injecting its JWT into localStorage (a fresh browser context per test).
4. Runs the full suite — ~44 spec files scoped by --project groups (see ddev e2e --help).

To run one group or one test:

ddev e2e moderation                                        # only the moderation group
ddev npm run test:e2e -- --project=moderation --grep "admin warns"

What the tests cover (selected)

…and ~30 more (threads, search, presence, DMs, attachments, mobile, admin, etc.).

Environment variables

ddev setup writes .env.local automatically — VITE_SERVER_INFO_URL for the app plus the E2E_* origins for Playwright, all derived from your DDEV hostnames. Edit them only if you need non-default backends. (.env.example documents VITE_SERVER_INFO_URL; the E2E_* vars are added by ddev setup.)

Production deployments configure the app at runtime (no rebuild) via the container env — see .env.prod.example and the Quick Start.

Contributing

See the contribution guide and code guidelines. CI runs typecheck, lint, unit tests and the production build on every pull request.

License

MIT.