AXTON

Why AXTON?

• Schema-driven. Define your models and local mutations in a schema. AXTON handles the local state changes.
• Type-safe end to end. Get typed client calls and backend read/write interfaces from the same schema.
• Works offline. Read and write local SQLite without a connection. AXTON persists changes and syncs in the background.
• Your backend. Implement your own read and write logic and choose your database. No vendor cloud service required.

Why local-first?

Local-first apps read and write data on the device, so everyday interactions don't wait for a network round trip. Users can keep working through a slow or missing connection, with changes saved locally and synchronized when the network is available.

How it works

Protocol 5 uses fresh canonical framework storage: one Client, physical SQLite file and Stream, plus a fresh backend framework namespace. Existing layouts are refused intact; no old-format migration or compatibility bridge is supplied. See adoption limits.

Clients push mutations over HTTP. On connection, they catch up from saved progress over HTTP, then receive ongoing record updates over WebSocket. AXTON manages this as one connection.

On your server, handlers process writes and loaders read records to send to clients. Each named Mutation commits its backend outcome independently; execution acknowledgment and locally committed settlement are separate boundaries. A Stream carries authoritative delivery. Track a record once; global invalidation of its authority reaches every tracking Stream, through the viewer's Loader.

Writes update local SQLite immediately, so reads see changes before sync completes. Changes to local data update query subscriptions (watch). If the backend rejects a mutation, its local changes roll back.

Current support

Layer	Supported today
Frontend / client	TypeScript · Flutter
Backend	TypeScript
Database	PostgreSQL through pg, Prisma or Drizzle

The TypeScript client and backend currently run on Node.js. The clients use native runtimes; browser support is not yet implemented. See platform validation for tested environments.

Need another language, runtime, or database adapter? Request support. More integrations can be added.

Build with AXTON

1. Define your models and mutations

Write your data models and local write operations (mutations) in a .model file:

model Todo {
  id    String
  title String
  done  Boolean
  @@id(id)
}

mutation AddTodo(todo Todo.create)
query SearchTodos(text String) { todos Todo[] }

A mutation may change business state; a query only reads. The compiler generates the client used below and the backend's Mutations, Queries and Loaders interfaces. See the schema compiler guide for generation commands.

2. Read and write locally

// Open the local database and connect.
import { GeneratedClient } from "./generated/client.ts";

const client = await GeneratedClient.open({
  path: "local.sqlite",
  stream: "User:demo-user",
  connection: {
    url: "http://127.0.0.1:4242",
    token: "demo-user",
  },
});

// Read.
const open = await client.models.todo.query({ where: { done: false } });

// Watch this query and render again when local data changes.
client.models.todo.watch({ where: { done: false } }, (todos) => render(todos));

// Run a Mutation. It commits locally and returns once it is queued;
// wait() also waits for this Store’s committed settlement.
const call = await client.mutations.addTodo({
  todo: { id: "t1", title: "Buy milk", done: false },
});
const { error } = await call.wait();

// Run a Query. It asks the backend directly and returns its result.
const { todos } = await client.queries.searchTodos({ text: "milk" });

// Await finite initial authority for the Stream supplied at open.
await client.bootstrap();

Rust sends immutable Mutation Batches and resumes finite authority delivery. Query/Fetch are fresh invocation snapshots, not queued calls; their null-cursor Models cannot replace current Stream protection. SDKs execute native networking and interface effects.

3. Implement handlers and loaders for your backend

This example uses Prisma with PostgreSQL through the included prisma shim.

// Handle a write using your database transaction.
const mutations: Mutations<Tx> = {
  async addTodo({ ctx, args }) {
    await ctx.tx.todo.create({ data: args.todo });

    // Track explicitly in the initiating authenticated Stream.
    ctx.stream.track.todo(args.todo);
  },
};

// Answer a read. Query contexts can track explicitly, but cannot invalidate.
const queries: Queries<Tx> = {
  async searchTodos({ ctx, args }) {
    const rows = await ctx.tx.todo.findMany({
      where: { title: { contains: args.text } },
      select: { id: true },
    });
    return { todos: rows };
  },
};

// Read the requested records from your database for sync.
const loaders: Loaders<Tx> = {
  todo: ({ ids, tx }) =>
    Promise.all(ids.map((identity) => tx.todo.findUnique({ where: identity }))),
};

Add these imports and the transaction type before the handlers and loaders above:

import { PrismaClient, type Prisma } from "@prisma/client";
import { prisma } from "@axtonjs/postgres/prisma";
import {
  createBackend,
  devAuth,
  type Mutations,
  type Queries,
  type Loaders,
} from "./generated/backend.ts";

type Tx = Prisma.TransactionClient;

Start the server after defining the handlers and loaders:

// Start the server.
const backend = createBackend({
  database: prisma(new PrismaClient()),
  authenticate: devAuth(),
  protocol5: {
    authorizeStream: (principal, stream) => stream === `User:${principal}`,
  },
  mutations,
  queries,
  loaders,
});
await backend.listen({ port: 4242 });

How AXTON compares with other sync frameworks

AXTON generates local operations from your schema and gives you typed interfaces to implement backend reads and writes.

Project	How local updates work	How backend writes work	How you define the read / sync path	Required backend database
AXTON	Generated local operations from your schema	You implement the business logic through a generated, typed write interface	You mark changes and define the read path through a generated typed read interface.	No fixed database
Replicache	You write local update functions	Your write API runs the requested operations	You implement a read API that returns data changes	No fixed database
Zero	You write local update functions	Your server functions handle each write	You define queries; Zero syncs matching database rows	PostgreSQL with database replication enabled
PowerSync	You update local SQLite	Your write API processes the changes	You define sync rules to select which database records reach each client	A supported database with change tracking enabled
Electric	You choose how to update local state	You choose how writes reach your backend	You define shapes to select Postgres rows for sync	PostgreSQL with database replication enabled
InstantDB	You update records through the SDK	Instant applies writes using your permission rules	You query through the SDK; Instant keeps the results up to date

AXTON needs a database adapter that provides consistent transactions and stores sync metadata. Replicache also requires consistent transaction snapshots.

Instant Cloud is closed to new signups and will shut down on August 31, 2027. You can still host Instant yourself. See the official announcement.

Project status

AXTON is an early alpha: its API is unstable and it is not ready for production use. Existing integrations must follow the AXTON rename notes before upgrading from a pre-rename build.

Schema guide · Client guide · Backend guide

Integration names

Rust crates use axton-* and imports use axton_*; the compiler command is axton. JavaScript packages use @axtonjs/*; unpublished React Native packages retain @axton/*. Dart imports use package:axton/axton.dart. Native libraries and C symbols use axton; the Expo module is AxtonNative. Environment variables use AXTON_*. Storage admission and adoption limits belong to Protocol 5 adoption.