Installation

By the end of this page the tutorial app will have a running client, an identity, and the space it keeps its records in.

Before you start

The Client is the app’s way into ECHO. It holds the databases of the spaces you belong to, on the device, and connects them to the network so peers can replicate them.

A client acts for an identity. The identity owns the spaces it creates, and other peers recognize it when it joins theirs. A space is a database that a set of identities replicate between them, and every object lives in exactly one space. The app keeps all its records in one space, called Contacts.

1. Install the client. @dxos/client holds the Client, and it brings @dxos/echo with it.

   pnpm

   pnpm add @dxos/client

   npm

   npm install --save @dxos/client

   yarn

   yarn add @dxos/client

   In a React app, install @dxos/react-client instead and follow the React guide.

2. Configure the bundler. In the browser, ECHO loads WebAssembly in the page and in workers, so Vite needs vite-plugin-wasm for both. ConfigPlugin loads the client’s config from YAML files at the package root.

   vite.config.ts

   export default defineConfig({
     plugins: [ConfigPlugin({ root: import.meta.dirname, env: ['MY_ENV_VAR'] }), wasm()],
     worker: {
       format: 'es',
       plugins: () => [wasm()],
     },
   });
   
   

   @dxos/config/rollup-plugin and @dxos/config/esbuild-plugin export the same ConfigPlugin for Rollup and esbuild. Node needs no bundler setup.

3. Open the app’s space. The app does this in one function. new Client takes the app’s types, which the next page declares. initialize opens local storage and connects to the network. The client then needs an identity before it can create a space; HALO covers identities and devices. Last, it creates the space and waits until its database is ready.

   /** Starts a client that knows the app's types, gives it an identity, and creates the space the app keeps its records in. */
   export const openContacts = async (services?: ClientServicesProvider) => {
     const client = new Client({ types, services });
     await client.initialize();
     if (!client.halo.identity.get()) {
       await client.halo.createIdentity();
     }
   
     const space = await client.spaces.create({ name: 'Contacts' });
     await space.waitUntilReady();
     return { client, space };
   };
   
   

   space.db is the database the rest of the learning path reads and writes. services is for running the client somewhere other than the default, as the embeds on these pages do: each runs its clients in memory in the page.

Configure the client

new Client() uses built-in defaults. Pass a Config to choose where settings come from. Each source is a function from @dxos/config, and earlier sources override later ones.

Defaults from a file

Defaults returns the config in dx.yml. In Node it reads config/default.yml in your project instead.

const fromDefaults = new Client({ config: new Config(Defaults()) });

Local development

Local returns the config in dx-local.yml, so a development preset can sit beside the defaults. In Node, Local returns nothing.

const forLocalDevelopment = new Client({ config: new Config(Local(), Defaults()) });

Environment variables

Envs maps environment variables to config paths, as listed in dx-env.yml.

const fromEnvironment = new Client({ config: new Config(Envs(), Local(), Defaults()) });

Each entry in dx-env.yml names a variable, the config path it sets, and its type:

LOG_FILTER:
  path: runtime.client.log.filter
  type: string

DX_PERSIST:
  path: runtime.client.storage.persistence
  type: boolean

Tip

Vite exposes only variables prefixed with VITE_. To read any other variable at build time, list it in the env option of ConfigPlugin, as in step 2. Its value appears at the config path runtime.app.env.MY_ENV_VAR.

What you can do now

You can install ECHO, configure a client for the browser or Node, and open the app’s space with an identity.

Next

Defining types: declare the app’s organizations, people and events.