Skip to content
DXOS LogotypeDXOS LogotypeDXOS Documentation

Configuration

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

Section titled “Defaults from a file”

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

import { 
class Client
The Client class encapsulates the core client-side API of DXOS.
Client, 
class Config
Global configuration object.
NOTE: Config objects are immutable.
Config } from '@dxos/client';
import { 
const Defaults: (basePath?: string) => ConfigInit
JSON config.
Defaults } from '@dxos/config';


const 
const fromDefaults: Client
fromDefaults = new 
new Client(options?: ClientOptions): Client
The Client class encapsulates the core client-side API of DXOS.
Client({ 
config?: Config | undefined
Client configuration object.
config: new 
new Config(config?: ConfigInit, ...objects: ConfigInit[]): Config
Creates an immutable instance.
@constructor
Config(
function Defaults(basePath?: string): ConfigInit
JSON config.
Defaults()) });

Local development

Section titled “Local development”

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

import { 
class Client
The Client class encapsulates the core client-side API of DXOS.
Client, 
class Config
Global configuration object.
NOTE: Config objects are immutable.
Config } from '@dxos/client';
import { 
const Defaults: (basePath?: string) => ConfigInit
JSON config.
Defaults, 
const Local: () => ConfigInit
Development config.
Local } from '@dxos/config';


const 
const forLocalDevelopment: Client
forLocalDevelopment = new 
new Client(options?: ClientOptions): Client
The Client class encapsulates the core client-side API of DXOS.
Client({
  
config?: Config | undefined
Client configuration object.
config: new 
new Config(config?: ConfigInit, ...objects: ConfigInit[]): Config
Creates an immutable instance.
@constructor
Config(
function Local(): ConfigInit
Development config.
Local(), 
function Defaults(basePath?: string): ConfigInit
JSON config.
Defaults()),
});

Environment variables

Section titled “Environment variables”

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

import { 
class Client
The Client class encapsulates the core client-side API of DXOS.
Client, 
class Config
Global configuration object.
NOTE: Config objects are immutable.
Config } from '@dxos/client';
import { 
const Defaults: (basePath?: string) => ConfigInit
JSON config.
Defaults, 
const Envs: (basePath?: string) => ConfigInit
ENV variable (key/value) map.
Envs, 
const Local: () => ConfigInit
Development config.
Local } from '@dxos/config';


const 
const fromEnvironment: Client
fromEnvironment = new 
new Client(options?: ClientOptions): Client
The Client class encapsulates the core client-side API of DXOS.
Client({
  
config?: Config | undefined
Client configuration object.
config: new 
new Config(config?: ConfigInit, ...objects: ConfigInit[]): Config
Creates an immutable instance.
@constructor
Config(
function Envs(basePath?: string): ConfigInit
ENV variable (key/value) map.
Envs(), 
function Local(): ConfigInit
Development config.
Local(), 
function Defaults(basePath?: string): ConfigInit
JSON config.
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

Loading the files in the browser

Section titled “Loading the files in the browser”

In the browser, Defaults, Local and Envs read what the bundler puts in the page. Add ConfigPlugin from @dxos/config/vite-plugin to the plugins in vite.config.ts, and it loads the three files from the package root:

ConfigPlugin({ root: import.meta.dirname, env: ['MY_ENV_VAR'] }),

Vite exposes only variables prefixed with VITE_. To read any other variable at build time, list it in env. Its value appears at the config path runtime.app.env.MY_ENV_VAR. @dxos/config/rollup-plugin and @dxos/config/esbuild-plugin export the same ConfigPlugin for Rollup and esbuild. The tutorial app passes its config in code, as in Installation, so it has no ConfigPlugin.