Quick Start
Quick Start Guide
DXOS is the developer platform for collaborative, offline-first, privacy-preserving software. This guide shows how to use ECHO for state consensus and HALO for decentralized identity.
DXOS works in any Node.js or Browser environment. There is a TypeScript API and a react
API.
In this guide
- Installation and usage.
- Using with React.
- Project templates.
- Deploy to Netlify.
Installation and usage
For any node
or browser build such as vite
, or rollup
(for react
see below):
npm install --save @dxos/client
Create and initialize a Client
:
import { Client } from '@dxos/client';
// create a client
const client = new Client();
const main = async () => {
await client.initialize();
// use client here
};
main();
An Options object can be passed to Client()
. See configuration examples.
To begin manipulating data, we must create an identity, and join or create a space.
See below for react
usage, otherwise see the TypeScript Guide.
Usage with React
Use @dxos/react-client
for react
hooks to access and manipulate data in ECHO and HALO.
npm install --save @dxos/react-client
Create a ClientProvider
to wrap your application. This allows nested components to use the hooks.
import React from 'react';
import { createRoot } from 'react-dom/client';
import { ClientProvider } from '@dxos/react-client';
import { useQuery, useSpaces } from '@dxos/react-client/echo';
import { useIdentity } from '@dxos/react-client/halo';
const Component = () => {
// Get the user to log in before a space can be obtained.
const identity = useIdentity();
// Get the first available space, created with the identity.
const [space] = useSpaces();
// 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 />);
Components will automatically re-render when the data changes. Change the data by mutating it as any regular JavaScript object.
For a step-by-step walkthrough, see the react tutorial.
Project templates
DXOS project templates are based on vite
, typescript
, react
, tailwind
, pwa
, and other opinions to get you going quickly.
Ensure node -v
is at version 18 or higher (recommend Node Version Manager).
Initialize an empty folder with npm create
like this:
npm create @dxos@latest
Note
If you encounter an error with EINVALIDPACKAGENAME
it's likely the npm/node versions are out of date. Ensure node -v
is 18 or higher and npm -v
is 9 or higher.
Then, use your favorite package manager such as yarn
, npm
or pnpm
:
npm install
npm run serve
This will start the development server and print a URL to the console. Opening two browser windows can demonstrate local state sync working:
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 OPFS or IndexedDB, controlled by the
halo.dxos.org
domain. This enables privacy and gives end-users control over their data. The app running onlocalhost
subscribes to data through a local shared memory connection with the HALO PWA onhalo.dxos.org
which is fast and works offline. Learn more about the HALO vault topology. - Remote peers exchange data directly, peer-to-peer over secure WebRTC 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 ORMs. 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.
Deployment
By default DXOS template apps are static, Progressive Web Apps that work offline. They can be deployed with any regular static hosting technique like Netlify, Vercel, CloudFlare, GitHub Pages, an S3 bucket, and others.
The build command is npm run build
which produces a static bundle in the output folder out/<app-name>
, which can be changed in vite.config.ts
.
For example, with Netlify:
- Go to "Add new site", and click "Import an existing project."
- Link to your application's repository.
- Set the build command and output directory.
- Publish!
If you would like to host the application yourself, see our guide on using KUBE for self-sovereign hosting.
Next steps
- Step-by-step React tutorial
- ECHO with React
- ECHO with TypeScript
- ECHO with strongly typed objects
We hope you'll find the technology useful, and we welcome your ideas and contributions:
- Join the DXOS Discord
- DXOS repository on GitHub
- File a bug or idea in Issues
Happy building! 🚀