Configuration examples

Custom signaling server

To use a local KUBE signaling server instead of the public default:

import { Client, Config } from '@dxos/client';

const client = new Client({
  config: new Config({
    runtime: {
      services: {
        signaling: [{
          server: 'wss://kube.dxos.org/.well-known/dx/signal'
        }]
      }
    }
  })
});

Custom HALO source

By default the client will use https://halo.dxos.org as the storage vault, but if there was a version of HALO deployed to a local KUBE, the remoteSource configuration value can be used to point the client to it:

import { Client, Config } from '@dxos/client';

const client = new Client({
  config: new Config({
    runtime: {
      client: {
        remoteSource: 'http://halo.localhost/vault.html'
      }
    }
  })
});

To deploy a locally operated HALO application, clone the dxos repo, and follow the repository guide to set up a local HALO build. HALO is a regular DXOS application with a dx.yml configuration file. You should be able to start up a local KUBE and deploy to it.

Config Plugin

@dxos/config provides plugins for a number of bundlers which allow the config to be loaded from yaml files at the package root rather than specified inline.

// vite.config.ts
import { defineConfig } from 'vite';
import { ConfigPlugin } from '@dxos/config/vite-plugin';

export default defineConfig({
  ...
  plugins: [
    ConfigPlugin(),
    ...
  ]
});

// rollup.config.js
import { ConfigPlugin } from '@dxos/config/rollup-plugin';

export default {
  ...
  plugins: [
    ConfigPlugin(),
    ...
  ]
};

import { build } from 'esbuild';
import { ConfigPlugin } from '@dxos/config/esbuild-plugin';

await build({
  ...
  bundle: true,
  plugins: [
    ConfigPlugin(),
    ...
  ]
})

// webpack.config.js
import { ConfigPlugin } from '@dxos/config/webpack-plugin';

module.exports = {
  ...
  plugins: [
    new ConfigPlugin(),
    ...
  ]
};

This allows config to be defined using one or more of the follow functions:

Loading config defaults from a file

Any config included in the dx.yml file will be returned by Defaults.

import { Client, Config } from '@dxos/client';
import { Defaults } from '@dxos/config';

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

Note

In a Node environment, Defaults loads from a config/default.yml file in your project.

Dynamic app configuration from KUBE

If your app is being hosted on a KUBE, use Dynamics to receive more specific configuration from that KUBE. With this mechanism, KUBE can serve apps in ways that redirect them to different signaling servers or HALO identity vaults.

import { Client, Config } from '@dxos/client';
import { Defaults, Dynamics } from '@dxos/config';

const client = new Client({
  config: new Config(await Dynamics(), Defaults())
});

Tips

The Config constructor uses lodash.merge to combine config objects. Earlier objects will take precedence over later objects, so Defaults should come last.

Note

If you want to provide config only for local-development, try including a dx-dev.yml file. If not being served from a KUBE, Dynamics will return the config from this file.

App configuration with environment variables

The config plugin provides an easy way to map environment variables to config values using the dx-env.yml file.

import { Client, Config } from '@dxos/client';
import { Defaults, Dynamics, Envs } from '@dxos/config';

const client = new Client({
  config: new Config(await Dynamics(), await Envs(), Defaults())
});

This file takes the following format:

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

LOG_PREFIX:
  path: runtime.client.log.prefix
  type: string

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

Loading app-specific environment variables

Bundlers such as Vite will automatically provide access to any enviroment variables prefixed with VITE_, however sometimes it's not convenient to prefix every variable you need access to. The config plugin provides a way to load arbitrary enviroment variables at build time.

// vite.config.ts
import { defineConfig } from 'vite';
import { ConfigPlugin } from '@dxos/config/vite-plugin';

export default defineConfig({
  ...
  plugins: [
    ConfigPlugin({
      env: ['MY_ENV_VAR']
    }),
    ...
  ]
});

This can then be accessed at the config path runtime.app.env.MY_ENV_VAR.