Quickstart Guide

Tonk follows a simple two-mode workflow:

Workers stream data in - Background services connect to external APIs or your file system and stream data into your local Tonk store
Apps visualise data - Frontend applications provide interfaces to explore and interact with that data

This architecture separates data ingestion from visualisation, making your applications more maintainable and your data more reusable across different interfaces.

Installing Tonk

First, you'll need to install Tonk on your machine:

npm install -g @tonk/cli && tonk hello

This will install the Tonk CLI globally and run the hello command, which sets up the Tonk daemon for synchronising your data.

The Tonk Workflow

Mode 1: Create Workers (Data Ingestion)

Workers are background services that connect to the outside world and stream data into your Tonk store. Start by creating a worker:

tonk create  # choose 'worker' when prompted
cd my-worker

Workers handle tasks like:

Syncing data from Google Maps, Gmail, or other APIs
Processing scheduled tasks
Real-time data streaming
API integrations

Example worker structure:

// src/index.ts - Your worker's main logic
app.post('/tonk', async (req, res) => {
  // Connect to external API
  const data = await fetchFromExternalAPI();
  
  // Store in Tonk via keepsync
  await writeDoc('my-collection/data', data);
  
  res.json({ success: true });
});

Mode 2: Create Apps (Data Visualisation)

Once you have data flowing in via workers, create frontend apps to visualise and interact with that data:

tonk create  # choose 'react' when prompted
cd my-app

Apps are React applications that:

Connect to your Tonk stores
Provide interfaces for your data
Enable real-time collaboration
Work offline-first

The CLI will scaffold a project with:

React, TypeScript, and Tailwind CSS
Keepsync for accessing your data stores
Development tools

Development Workflow

Start Your Worker

First, get your worker running to begin data ingestion:

cd my-worker
pnpm dev

tonk worker register
tonk worker start my-worker

Start Your App

Then start your frontend app and navigate to http://localhost:3000 in the browser:

cd my-app
pnpm dev

This will:

Start a development server with hot reloading (so changes in the code are instantly reflected)
Connect to your Tonk stores (where workers are streaming data)

Understanding the Data Flow

The magic happens through Tonk Stores - shared data containers that connect workers and apps:

External APIs → Workers → Tonk Stores → Apps → Users
                  ↑                ↓
                  └ Real-time sync ┘

In Workers: Writing Data

Workers stream data into stores using keepsync:

import { writeDoc } from '@tonk/keepsync';

// Worker streams in location data
await writeDoc('locations/favorites', {
  places: googleMapsData,
  lastSync: Date.now()
});

In Apps: Sculpting Data

Apps connect to these stores allowing you to perform sophisticated actions over your data.

import { create } from "zustand";
import { sync } from "@tonk/keepsync";

// App reads and displays the same data
const useLocationStore = create(
  sync(
    (set) => ({
      locations: [],
      // ... your app logic
    }),
    { docId: "locations/favorites" }
  )
);

Key Benefits

Separation of concerns: Workers handle data, apps handle logic and rendering
Real-time sync: Changes appear instantly across all connected apps
Offline-first: Everything works without internet, syncs when reconnected
No database complexity: No migrations, caching, or auth headaches
Collaborative: Multiple users see updates in real-time

Deployment Options

Tonk provides several ways to deploy your workers and apps:

Local Deployment

Build and serve locally:

# Build your app
pnpm run build

# Push the bundle to Tonk
tonk push

# Start hosting the bundle
tonk start <bundleName>

One-Touch Hosting (Experimental)

For quick deployment to the cloud:

tonk deploy

⚠️ Note: This is experimental and requires an access code. Contact Tonk support for access.

Docker & Production

For production deployments, Tonk includes Docker support and cloud deployment options.

Next Steps

Learn Workers: Tonk Workers Guide - Create background services
Learn Keepsync: Keepsync Guide - Master data synchronization
Deploy to Production: Deployment Guide - Docker, cloud, and hosting options
CLI Reference: Command Reference - Complete command documentation

Real-World Examples

Check out these complete examples in the repository:

Google Maps Locations Worker - Syncs your saved places from Google Maps
My World App - Visualizes location data on an interactive map
File Browser App - Browse and manage files with real-time sync

Tonk Docs