This tutorial walks through creating the UI for a basic Replicache-powered todo list.
It relies on the replicache-sample-todo backend. To learn how to setup you own Replicache backend, see Server Side Setup.
If you have any problems or questions, please join us on Slack. We'd be happy to help.
You can also skip to the end and check out the full working version of this sample.
Note: This document assumes you already know what Replicache is, why you might need it, and broadly how it works. If that's not true check out the design document for a detailed deep-dive.
npm install replicache
<script type="module">
import Replicache from 'replicache'; // Replace with a real module path as needed...
const rep = new Replicache({
// URL that serves the Client View. The Diff Server pulls new Client Views
// from this URL. See
// https://github.com/rocicorp/replicache/blob/main/SERVER_SETUP.md for more
// information on setting up your Client View.
clientViewURL:
'https://replicache-sample-todo.now.sh/serve/replicache-client-view',
// URL of the Diff Server to use. The Replicache client periodically fetches
// the Client View from your service through the Diff Server, which returns
// a delta to the client. You can use our hosted Diff Server (as here) or
// a local Diff Server, which can be useful during development. See
// https://github.com/rocicorp/replicache/blob/main/SERVER_SETUP.md for more
// information on setting up your Client View or a local Diff Server.
diffServerURL: 'https://serve.replicache.dev/pull',
// Auth token for the Diff Server. When running against the
// replicache-sample-todo backend as here, this value should be '1'. To run
// against your own backend, replace this value with the Account ID assigned
// when creating a Replicache account at https://serve.replicache.dev/signup.
diffServerAuth: '1',
// URL of your service's Replicache batch endpoint. Replicache
// will send batches of mutations here for application.
batchURL: 'https://replicache-sample-todo.now.sh/serve/replicache-batch',
// Auth token for your client view and batch endpoints. You can use this value
// '2' when running against the replicache-sample-todo backend.
dataLayerAuth: '2',
});
</script>Use subscribe() to open standing queries. Replicache calls onData whenever the result of the query changes, either because of local changes or sync.
rep.subscribe(
async tx => {
return await toArray(tx.scan({prefix: '/todo/'}));
},
{
onData: result => {
// Using lit-html, but the principle is the same in any UI framework.
// See https://github.com/rocicorp/replicache-sdk-js/tree/main/sample/cal
// for an example using React.
const toggle = complete =>
html`<td><input type="checkbox" .checked=${complete} /></td>`;
const title = text => html`<td>${text}</td>`;
const row = todo =>
html`<tr>
${toggle(todo.complete)}${title(todo.text)}
</tr>`;
render(
html`<table>
${result.map(row)}
</table>`,
document.body,
);
},
},
);Register client-side mutators using register().
Mutators run completely locally, without waiting on the server — online, offline, whatever! A record of the mutation is queued and sent to your service's batch endpoint when possible.
Replicache also invokes mutators itself, during sync, to replay unacknowledged changes on top of newly received server state.
const updateTodo = rep.register('updateTodo', async (tx, {id, complete}) => {
const key = `/todo/${id}`;
const todo = await tx.get(key);
todo.complete = complete;
await tx.put(key, todo);
});
const handleCheckbox = async (id, e) => {
await updateTodo({id, complete: e.srcElement.checked});
};- We recommend enabling console persistence while developing replicache-enabled apps to make debugging easier.
- Remember that data changes can happen "underneath" you and cause
subscribe()to re-fire at any time. These changes can come from the server or from a different tab. If your UI is not reactive (driven solely by the data model) you need to take extra steps to ensure the UI is in sync with the data.
That's it! You've built a fully-functioning offline-first todo app against our sample backend. What will you do next?