DXOS

Getting started

About 4 min

Getting started

DXOS is the developer platform for collaborative, offline-first, privacy-preserving software.

Learn about the mission.

In this guide

  • Starting a react project with an app template.
  • Using ECHO for real-time state consensus in react.
  • Using HALO for decentralized identity.
  • Starting a KUBE to host the app.
  • Deploying the app to KUBE.

Create an app

DXOS project templates are based on viteopen in new window, typescriptopen in new window, reactopen in new window, tailwindopen in new window, pwaopen in new window, and other opinions to get you going quickly.

DXOS works in any Node.js or Browser environment. There is a TypeScript API and a react API.

This guide will walk you through creating and deploying a react app.

Initialize an empty folder with npm init like this:

npm init @dxos

Then:

pnpm install
pnpm serve

Note

Only pnpmopen in new window is supported for now: npm i -g pnpm.

This will start the development server 🚀.

You should be able to open two windows pointed at the dev server and see reactive updates like in the video below.

Why this is cool:

  • State is being reactively shared between all instances of the app running on the same device. If more peers join the space, all of them will see updates reactively.
  • Data is stored locally, in-browser, in IndexedDBopen in new window, controlled by the halo.dxos.org domain. This enables privacy and gives end-users control over their data. The app running on localhost subscribes to data through a local shared memory connection with the HALO PWA on halo.dxos.org which is fast and works offline. Learn more about the HALO vault topology.
  • When remote peers join the same space, their changes are given to running apps through HALO in the same way.
  • Remote peers exchange data directly, peer-to-peer over secure WebRTCopen in new window connections.
  • User identity (public/private keys) are established securely and maintained by HALO for the whole device (browser profile), without a password.
  • Everything works offline.
  • Real-time collaboration is possible when online.
  • There are no servers that store any data.
  • There is no need for ORMsopen in new window. ECHO objects are "plain javascript" objects that can be manipulated directly.
  • There is no need for an API tier. The app has everything it needs on the client.

ECHO State Consensus

ECHO is a peer-to-peer graph database designed for offline-first and real-time collaboration. There is no central server, peers exchange data directly over p2p connections.

How to use ECHO

  1. Install @dxos/client or @dxos/react-client for react using npm, yarn, or pnpm.
  2. Create and initialize a Client or use a <ClientProvider /> in react.
  3. Establish a HALO identity.
  4. Create or join a space.
  5. Find objects with query or useQuery in react.
  6. Mutate the objects as you would plain JavaScript objects, and they will replicate with other peers for you. 🚀
import React from 'react';
import { createRoot } from 'react-dom/client';
import {
  ClientProvider,
  useIdentity,
  useOrCreateFirstSpace,
  useQuery,
} from '@dxos/react-client';

const Component = () => {
  // get the user to log in before a space can be obtained
  const identity = useIdentity({ login: true });
  // create or use the first space
  const space = useOrCreateFirstSpace();
  // grab everything in the space
  const objects = useQuery(space, {});
  // show the id of the first object returned
  return <>{objects?.[0]?.id}</>;
};

const App = () => (
  <ClientProvider>
    <Component />
  </ClientProvider>
);

createRoot(document.body).render(<App />);

Tip

To see an example without react see the TypeScript Guide

Mutations

Any objects coming from query or useQuery are tracked. Manipulate them directly:

const objects = useQuery(space, {});

const object = objects[0];
object.counter = 0;
object.name = 'example';

The above writes will start propagating to connected peers in the space on the next tick.

The changes will also cause any subscribed UI components in the app to re-render accordingly as well.

Creating new objects:

import { Document } from '@dxos/react-client';

const newThing = new Document();
newThing.someProperty = 'example';

space.experimental.db.save(newThing);

This will begin tracking further changes on the object and replicating them to other peers.

Recap

  • A HALO identity and a space are required to use ECHO.
  • Reading objects is as simple as space.query() in TypeScript or useQuery() in react.
  • The objects returned are tracked by the Client and direct mutations to them will be synchronized with other peers (and other parts of your app) reactively.

Next steps

Continue reading below about how to deploy and host the app, or jump to:

Starting a KUBE

KUBE hosts and serves applications and provides supporting services like peer network discovery.

Install KUBE:

sudo bash -c "$(curl -fsSL https://install-kube.dxos.org)"

Then:

sudo kube start # start the service in the background
kube status # verify it's running

Once KUBE is running, applications can be deployed to it. 🚀

Learn more about what services KUBE provides.

Deploying apps to KUBE

To deploy to KUBE, first ensure a KUBE is running as above.

If using a DXOS application template:

pnpm run deploy

Otherwise, to deploy any static application:

  • Ensure the dx CLI is installed
  • Ensure there is a dx.yml file in the project root
  • Run dx app publish

The app will be accessible in a browser at http://<app-name>.localhost where <app-name> is found in dx.yml. 🚀

For example, and app created with dx app create hello, the app will be on hello.localhostopen in new window by default.

Caution

Your app will now always be available on your machine until KUBE or the specific app is stopped.

Tunneling

KUBE can expose apps to the world wide web and provide URLs that can be used to reach them from anywhere on the internet.

Simply set tunnel: true in dx.yml and redeploy. Read more about KUBE tunneling.

Next steps

This guide demonstrated how to create and deploy a local-first DXOS application.

Using DXOS:

We hope you'll find the technology useful, and we welcome your ideas and contributions:

Happy building! 🚀