Your profile

By the end of this page the contact book will create your identity with a profile the first time it runs, show your name from it in the corner, and let you change it.

To write the code as you read, open the starter on StackBlitz. It is the finished app with the code from these pages taken out. It runs from the start, and when the app reaches code you have not written yet, a line at the top names the step and its file. Each sample on these pages is titled with the file it goes in, and numbered as that file is.

Follow along in StackBlitz

Background

An identity stands for you. In Keyhive, which HALO is built on, it is a group named by a DID, such as did:halo:BA25QRC2…. Its members are your devices, and the first member is the device that creates it. No server issues the identity; the client makes it on the device, with no network needed.

The identity also has a profile: a display name, and any other data the app wants, such as an avatar. Everyone you share a space with sees it.

The code is Effect. @dxos/halo describes each operation as an Effect or a Stream that needs Identity.Service or Space.Service. @dxos/halo-adapter-client makes both from a client, and @dxos/halo-react hands them to the components through React context, with hooks that follow the streams.

Steps

1. Install the packages. @dxos/client holds the client, @dxos/halo the API these pages use, @dxos/halo-adapter-client the services between them, and @dxos/halo-react the provider for React. Until the next npm release, install the build of main these pages describe, from pkg.pr.new.

   pnpm

   pnpm add https://pkg.pr.new/dxos/dxos/@dxos/client@20a14b9 https://pkg.pr.new/dxos/dxos/@dxos/halo@20a14b9 https://pkg.pr.new/dxos/dxos/@dxos/halo-adapter-client@20a14b9 https://pkg.pr.new/dxos/dxos/@dxos/halo-react@20a14b9 effect@4.0.4

   npm

   npm install --save https://pkg.pr.new/dxos/dxos/@dxos/client@20a14b9 https://pkg.pr.new/dxos/dxos/@dxos/halo@20a14b9 https://pkg.pr.new/dxos/dxos/@dxos/halo-adapter-client@20a14b9 https://pkg.pr.new/dxos/dxos/@dxos/halo-react@20a14b9 effect@4.0.4

   The browser setup is the same as ECHO’s; see Installation for the Vite config. The StackBlitz project has it already.

2. Configure the client. The client keeps the device’s keys and data on the device, and reaches other devices through EDGE, DXOS’s network, which relays invitations and replicates spaces.

   src/app/App.tsx

   import { Config } from '@dxos/config';
   import { Identity, Space } from '@dxos/halo';
   import {
     makeIdentityService,
     makeSpaceService,
   } from '@dxos/halo-adapter-client';
   import { HaloProvider, type HaloServices } from '@dxos/halo-react';
   
   import { ContactBook } from './ContactBook.tsx';
   
   /**
    * Keeps the app's keys and data on the device and reaches other devices
    * through DXOS's EDGE network, which relays invitations and replicates spaces.
    */
   const config = new Config({
     runtime: {
       client: {
         storage: { persistent: true },
         edgeFeatures: {
           signaling: true,
           subductionReplicator: true,
           feedReplicator: true,
         },
       },
       services: {
         edge: { url: 'https://dxos.network/' },
         iceProviders: [{ urls: 'https://dxos.network/ice' }],
       },
     },
   });
   
   

3. Start the client. openHalo starts a client and returns it with the HALO services it backs. The app calls it once, at startup, and puts the services in a HaloProvider. Below it, a component gets them with useHaloServices() and runs each piece of HALO code with Effect.provide(services) and Effect.runPromise.

   src/app/App.tsx

   import * as Context from 'effect/Context';
   import React, { useEffect, useState } from 'react';
   
   // `@dxos/keys` reads `Buffer` as it loads, so the globals go in before the client.
   import '@dxos/node-std/globals';
   import { Client, type ClientServicesProvider } from '@dxos/client';
   import { Config } from '@dxos/config';
   import { Identity, Space } from '@dxos/halo';
   import {
     makeIdentityService,
     makeSpaceService,
   } from '@dxos/halo-adapter-client';
   import { HaloProvider, type HaloServices } from '@dxos/halo-react';
   
   import { ContactBook } from './ContactBook.tsx';
   
   /**
    * Keeps the app's keys and data on the device and reaches other devices
    * through DXOS's EDGE network, which relays invitations and replicates spaces.
    */
   const config = new Config({
     runtime: {
       client: {
         storage: { persistent: true },
         edgeFeatures: {
           signaling: true,
           subductionReplicator: true,
           feedReplicator: true,
         },
       },
       services: {
         edge: { url: 'https://dxos.network/' },
         iceProviders: [{ urls: 'https://dxos.network/ice' }],
       },
     },
   });
   
   /** Starts a client, and returns it with the HALO services it backs. */
   export const openHalo = async (clientServices?: ClientServicesProvider) => {
     const client = new Client(
       clientServices
         ? { services: clientServices }
         : {
             config,
             // Keeps the device's keys and data in the browser's private file system.
             createOpfsWorker: () =>
               new Worker(new URL('@dxos/client/opfs-worker', import.meta.url), {
                 type: 'module',
               }),
           },
     );
     await client.initialize();
     const services = Context.empty().pipe(
       Context.add(Identity.Service, makeIdentityService(client)),
       Context.add(Space.Service, makeSpaceService(client)),
     );
     return { client, services };
   };
   
   

4. Create your identity. Identity.create makes the identity, with this device as its first member, and gives its profile your name. Start on the welcome screen calls this.

   src/app/Welcome.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity } from '@dxos/halo';
   import { useHaloServices } from '@dxos/halo-react';
   
   import { type Stage, reached } from '../stage.ts';
   import { Guest } from './Invitations.tsx';
   import { Prompt } from './ui.tsx';
   
   /** The device before it has an identity: start one, join one from another device, or recover one. */
   export const Welcome = ({ stage }: { stage: Stage }) => {
     const services = useHaloServices();
     const [mode, setMode] = useState<'new' | 'device' | 'recover'>('new');
     // Focusing the first field on load would scroll the page to the embed.
     const [picked, setPicked] = useState(false);
     const pick = (next: typeof mode) => {
       setPicked(true);
       setMode(next);
     };
   
     /** Creates the identity, with this device as its first member. */
     const handleStart = (name: string) =>
       Identity.create({ displayName: name }).pipe(
         Effect.provide(services),
         Effect.runPromise,
       );
   
   

5. Follow your identity. useIdentity returns the identity, or undefined before there is one, and re-renders the component on every change. It follows Identity.identity, a stream of the identity. The contact book reads it to show either the welcome screen or your name.

   src/app/ContactBook.tsx

   import { useIdentity, useSpaces } from '@dxos/halo-react';
   import { type SpaceId } from '@dxos/keys';
   
   import { type Stage, reached } from '../stage.ts';
   import { Contacts, Members } from './Contacts.tsx';
   import { Devices } from './Devices.tsx';
   import { InviteBar } from './Invitations.tsx';
   import { ProfileChip } from './Profile.tsx';
   import { Recovery } from './Recovery.tsx';
   import { SpacePicker } from './Spaces.tsx';
   import { Boundary } from './ui.tsx';
   import { Welcome } from './Welcome.tsx';
   
   export type ContactBookProps = {
     stage: Stage;
   };
   
   /**
    * The contact book on one device, with what `stage` has built. It runs against
    * the HALO services of the `HaloProvider` above it.
    */
   export const ContactBook = ({ stage }: ContactBookProps) => {
     /** The identity, re-rendering on each change; undefined before it exists. */
     const identity = useIdentity();
   
   

6. Change your profile. Identity.updateProfile writes a new profile. useIdentity re-renders with it, and so does every space member list that includes you. Clicking your name, then Save, calls this.

   src/app/Profile.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity } from '@dxos/halo';
   import { useHaloServices } from '@dxos/halo-react';
   
   import { Prompt, initial } from './ui.tsx';
   
   /** Your name, which you click to change. */
   export const ProfileChip = ({ name }: { name?: string }) => {
     const services = useHaloServices();
     const [editing, setEditing] = useState(false);
   
     /** Changes the name everyone who shares a space with you sees. */
     const handleRename = (name: string) =>
       Identity.updateProfile({ displayName: name }).pipe(
         Effect.provide(services),
         Effect.runPromise,
       );
   
   

Try it

This device has no identity yet. Type a name and press Start, then click your name to change it.

What you can do now

You can start a client, create an identity with a profile, follow it from a component, and change its profile. Next, Your spaces gives it somewhere to invite people.