useSandbox()
function useSandbox(): object
The main composable of Karagöz Sandbox.
Injects and uses the provided web container promise, performs bootstrapping and returns an object that is the central piece in the logic of the sandbox.
This composable is created as a shared instance (singleton, if you will) using VueUse's createSharedComposable().
Returns
object
bootstrap()
bootstrap: () => Promise<void>;
Bootstrap method. Should be called after the web container boots and the first batch of files
(most importantly package.json) are mounted.
Order of execution:
- Kill dependency installation and dev server if either of them is running.
- On first run: listen to URL change events in the preview iframe to emit the latest URL to the parent window. This is needed to show the current UR in address bar of the preview.
- Open a terminal window if allowed by the sandbox options.
- Install dependencies.
- Start dev server.
- On first run: watch the current working directory to re-bootstrap when a file changes that should trigger
re-install (e.g.
package.json).
Returns
Promise<void>
container
container: ComputedRef<null | WebContainer>;
A computed ref that gives access to the web container instance.
editorTabs
editorTabs: object;
Editor tabs manager. Responsible for opening, focusing and closing editor tabs.
editorTabs.close()
close: (id) => void;
Close a tab corresponding to given ID.
Parameters
id
string
Returns
void
editorTabs.current
current: ComputedRef<
| undefined
| Tab<EditorTabContext>>;
Computed ref containing the currently focused tab.
editorTabs.findTab()
findTab: (id) =>
| undefined
| Tab<EditorTabContext>;
Find the tab corresponding to given ID.
Parameters
id
string
Returns
| undefined
| Tab<EditorTabContext>
editorTabs.findTabIndex()
findTabIndex: (id) => number;
Find the tab index corresponding to given ID.
Parameters
id
string
Returns
number
editorTabs.open()
open: (id, label?, context?) => void;
Open an editor tab for a file. If the file is already open it is re-focused.
Parameters
id
string
file path, used as an ID as well
label?
string
context?
Returns
void
editorTabs.tabs
tabs: ComputedRef<Tab<EditorTabContext>[]>;
List of tabs.
editorTabs.updateContext()
updateContext: (id, setter) => void;
Update the context data of the tab corresponding to give ID.
Parameters
id
string
setter
(ctx) => EditorTabContext
a callback that receives the old context and returns the new context to be set.
Returns
void
explorer
explorer: object;
Provides matchers for different purposes. The matchers use ignore to determine whether a give path matches one of the patterns specified in the sandbox options.
explorer.hidden
hidden: ComputedRef<Ignore>;
Computed ref containing a function to determine whether an entity (directory or file) should be hidden in the file explorer.
explorer.readonly
readonly: ComputedRef<Ignore>;
Computed ref containing a function to determine whether an entity (directory or file) should be marked as readonly in the file explorer and editor tabs.
explorer.reinstall
reinstall: ComputedRef<Ignore>;
Computed ref containing a function to determine whether changing an entity (directory or file) should trigger the re-installation of dependencies and re-bootstrapping.
options
options: object;
options.editor
readonly editor: object;
Editor related options.
options.editor.suppressClose?
readonly optional suppressClose: boolean;
Default value to be used when creating editor tabs.
options.editor.theme?
readonly optional theme: object;
Themes to be used by codemirror.
Using callbacks to overcome the readonly nature of the options returned by useSandbox().
It is also to avoid the "Type instantiation is excessively deep and possibly infinite." error.
The callbacks return an array to allow passing multiple themes (e.g. base theme and a theme for overrides).
options.editor.theme.dark()?
readonly optional dark: () => Extension[];
Callback that returns a list of dark codemirror themes.
Returns
Extension
options.editor.theme.light()?
readonly optional light: () => Extension[];
Callback that returns a list of light codemirror themes.
Returns
Extension
options.explorer
readonly explorer: object;
Path patterns to be used for matching. The matchers use .gitignore-style matching through ignore to determine whether a give path matches one of the patterns.
options.explorer.hidden?
readonly optional hidden: readonly string[];
List of patterns to determine whether an entity (directory or file) should be hidden in the file explorer.
options.explorer.readonly?
readonly optional readonly: readonly string[];
List of patterns to determine whether an entity (directory or file) should be marked as readonly in the file explorer and editor tabs.
options.explorer.reinstall?
readonly optional reinstall: readonly string[];
List of patterns to determine whether changing an entity (directory or file) should trigger the re-installation of dependencies and re-bootstrapping.
options.preview
readonly preview: object;
Preview related options.
options.preview.suppressAddressBar?
readonly optional suppressAddressBar: boolean;
When true, the address bar in the preview panel will not be shown.
options.process
readonly process: object;
Preview / terminal related options.
options.process.commands
readonly commands: object;
Predefined commands.
options.process.commands.devServer
readonly devServer: string;
Command to start dev server.
Default
npm start
options.process.commands.install
readonly install: string;
Dependency installation command.
Default
npm install
options.process.commands.terminal
readonly terminal: string;
Command to start a terminal.
Default
jsh
options.process.packageManager
readonly packageManager: "npm" | "pnpm" | "yarn";
Package manager. Setting this option adjusts the predefined commands accordingly.
options.process.starters?
readonly optional starters: object;
Callbacks to spawn the processes of the predefined commands. Implemented as a sensible default and do some opinionated stuff.
If more control is needed, a process can be started using useSandbox().processTabs.open().
options.process.starters.devServer()?
readonly optional devServer: () => Promise<void>;
Dev server process starter.
Returns
Promise<void>
options.process.starters.install()?
readonly optional install: () => Promise<void>;
Dependency installation process starter.
Returns
Promise<void>
options.process.starters.terminal()?
readonly optional terminal: () => Promise<void>;
Terminal process starter.
Returns
Promise<void>
options.terminal
readonly terminal: object;
Terminal related options.
options.terminal.maxCount?
readonly optional maxCount: number;
Maximum number of terminal tabs to be opened simultaneously.
Default
3
options.terminal.theme?
readonly optional theme: object;
Theme to be used by xterm to output process and terminal logs.
Using callbacks to overcome the readonly nature of the options returned by useSandbox().
options.terminal.theme.dark()?
readonly optional dark: () => ITheme;
Callback to return dark xterm theme.
Returns
ITheme
options.terminal.theme.light()?
readonly optional light: () => ITheme;
Callback to return light xterm theme.
Returns
ITheme
preview
preview: object;
preview.frame
frame: Ref<undefined | HTMLIFrameElement> = previewFrame;
A reference to the preview iframe element.
preview.reload()
reload: () => Promise<void>;
Reload the preview.
Returns
Promise<void>
preview.suppressAddressBar
suppressAddressBar: ComputedRef<undefined | boolean>;
Computed ref containing a boolean flag. When true, the address bar in the preview panel will not be shown.
preview.url
url: ComputedRef<string>;
The preview URL.
processTabs
processTabs: object;
Process tabs manager. Responsible for opening, focusing and closing process and terminal tabs.
processTabs.availableTerminals
availableTerminals: ComputedRef<number>;
processTabs.close()
close: (id) => void;
Close the process tab corresponding to the given ID and kill the process attached to it.
Parameters
id
string
Returns
void
processTabs.current
current: ComputedRef<
| undefined
| Tab<ProcessTabContext>>;
Computed ref containing the currently focused tab.
processTabs.findTab()
findTab: (id) =>
| undefined
| Tab<ProcessTabContext>;
Find the tab corresponding to given ID.
Parameters
id
string
Returns
| undefined
| Tab<ProcessTabContext>
processTabs.findTabIndex()
findTabIndex: (id) => number;
Find the tab index corresponding to given ID.
Parameters
id
string
Returns
number
processTabs.kill()
kill: (id) => void;
Kill the process corresponding to the give ID.
Parameters
id
string
Returns
void
processTabs.open()
open: (id, label?, context?) => Promise<void>;
Open a process tab.If the process tab already exists, it is re-focused, otherwise the process will be started.
Parameters
id
string
label?
string
context?
Returns
Promise<void>
Example
useSandbox()
.processTabs
.open('npm install', 'Install', {
command: 'npm',
arguments: ['install', '--frozen-lockfile']
})
processTabs.restart()
restart: (id) => Promise<void>;
Restart the process corresponding to the given ID.
Parameters
id
string
Returns
Promise<void>
processTabs.tabs
tabs: ComputedRef<Tab<ProcessTabContext>[]>;
List of tabs.
processTabs.updateContext()
updateContext: (id, setter) => void;
Update the context data of the tab corresponding to give ID.
Parameters
id
string
setter
(ctx) => ProcessTabContext
a callback that receives the old context and returns the new context to be set.
Returns
void
setOption()
setOption: <K, T>(key, newValueOrSetter) => void;
Set an option. Ideally options are set before calling bootstrap().
Rather than allowing the direct mutation of the options object, the return of useSandbox() exposes a readonly
copy of the options and setOption() is used to set a specific option's value. This is to make sure that setting
options is intentional and not by mistake.
Type Parameters
• K extends keyof SandboxOptions
• T extends
| {
suppressClose: boolean;
theme: {
dark: () => Extension;
light: () => Extension;
};
}
| {
hidden: string;
readonly: string;
reinstall: string;
}
| {
suppressAddressBar: boolean;
}
| {
commands: {
devServer: string;
install: string;
terminal: string;
};
packageManager: "npm" | "pnpm" | "yarn";
starters: {
devServer: () => Promise<void>;
install: () => Promise<void>;
terminal: () => Promise<void>;
};
}
| {
maxCount: number;
theme: {
dark: () => ITheme;
light: () => ITheme;
};
}
Parameters
key
K
newValueOrSetter
either a new value or a callback that receives the old value to produce the new value.
T | (oldValue) => T
Returns
void
setPackageManager()
setPackageManager: (pm) => void;
Set the package manager option.
This affects only the predefined commands and processes (in SandboxOptions.process.commands).
Parameters
pm
"npm" | "pnpm" | "yarn"
Returns
void