Supplying Options

The sandbox returned by useSandbox exposes a method setOption which allows setting options for a specific aspect of the sandbox by providing a key and the value or callback to calculate the new value from the old value. For example:

sandbox.setOption('editor', { suppressClose: true })
// or
sandbox.setOption('editor', old => ({ ...old, suppressClose: true }))

Heads up!

While we will into more depth on some options in this page, the complete documentation of the options can be found in the API docs (see SandboxOptions).

You can retrieve a readonly copy of the options simply by accessing the options property on the sandbox instance:

// DO NOT try to set options through assignment here;
// use sandbox.setOption() instead.
sandbox.options.editor
sandbox.options.explorer
sandbox.options.preview
sandbox.options.process
sandbox.options.terminal

Editor Options

Key: editor

The editor options include:

suppressClose: when true, prevents the "close" icon from being shown for editor tabs. This behavior can be overridden for individual editor tabs.
theme: specifies the themes used to style the CodeMirror editors. It takes 2 callbacks for light and dark themes.

Explorer Options

Key: explorer

The explorer options are 3 sets of path matchers. Here they are along with their default values:

sandbox.setOption('explorer', {
  /* determine whether an entity (directory or file) should be hidden in the file explorer. */
  hidden: ['./node_modules/*'],
  /* determine whether an entity should be marked as readonly in the file explorer and editor tabs (lock icon). */
  readonly: [
    '*/node_modules',
    '*/package-lock.json',
    '*/pnpm-lock.yaml',
    '*/yarn.lock',
  ],
  /* determine whether changing an entity should trigger the re-installation of dependencies and re-bootstrapping. */
  reinstall: ['./package.json'],
})

Preview Options

Key: preview

A single option suppressAddressBar to determine whether to render the address bar above the preview frame.

Process Options

Key: process

Contain 3 options: packageManager, commands and starters.

packageManager sets the package manager to be used by the commands. Only relevant when commands and starters use the defaults. One of npm, pnpm and yarn.

The package manager must be set before sandbox.bootstrap() is called.

commands is an object with 3 keys: install, devServer and terminal which hold the text shell commands to run for default processes. The install and devServer are automatically adjusted when the packageManager option is changed.

Similarly, starters contains the same 3 keys: install, devServer and terminal, but in this case they are callbacks to start their respective processes. By default, they use their counterparts in commands. Which also means that when one of the keys of starters is set, its counterpart in commands is ignored.

sandbox.setOption('process', (old) => ({
  packageManager: 'pnpm', // so commands.install = "pnpm install" and commands.devServer = "pnpm start" 
  commands: {
    ...old.commands,
    devServer: 'pnpm dev', // overriding devServer command default
  },
  starters: {
    ...old.starters,
    terminal: () => { /* new terminal process logic */ }
  },
}))

Terminal Options

Key: terminal

The terminal options include:

maxCount: the maximum number of terminal tabs to be opened simultaneously. Default: 3.
theme: specifies the themes used to style XTerm. It takes 2 callbacks for light and dark themes.