Destiner's Notes

Using Sandpack Client

2 February 2022

In case you don’t know, Sandpack by Codesandbox is a library that enables any developer to inject a code sandbox inside their applications, abstracting any of the low-level engineerings.

Sandpack ships with a set of React components that provide an even higher level of abstractions, including multi-file support, built-in presets for popular environments, and text editor integration.

Here, however, we will take a look at Sandpack Client, which is a low-level sandboxing solution. Still, Client handles dependency management, bundling, output rendering, and more.

Why use Client

First of all, in most cases, you’d probably want to use React components instead.

One reason not to use React components is the lack of fine-grained control over the component library. For example, if you want to use a different text editor, you might want to use Client and write your own editor integration.

Another reason is using a different frontend framework. If you’re using Svelte or Vue, there’s no official sandpack integration for you. However, there are third-party packages that provide support for other frameworks (shameless plug: I’ve made a package that provides high-level Vue components on top of Sandpack).

Installation

To install Sandpack Client, run:

npm i @codesandbox/sandpack-client

Usage

You need to add an <iframe> to your page:

<iframe id="sandbox" />

In your script, initialize Sandpack:

import { SandpackClient } from '@codesandbox/sandpack-client';

const sandboxEl = document.getElementById('sandbox') as HTMLIFrameElement;
const client = new SandpackClient(sandboxEl, {
  files: {
    '/index.html': {
      code: `
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title></title>
  </head>
    <body>
      <h1>Sandpack Client Demo</h1>
    </body>
</html>`,
    },
  },
  entry: '/index.html',
  dependencies: {},
});

Tip: if you’re using Sandpack inside a frontend framework, it might be helpful to use ref to access the iframe reactively instead of referencing it by id. Also, you’ll likely first need to wait until the component is mounted. For example, in Vue you’d need to initialize Sandpack inside onMounted hook.

Configuration

You might want to customize the way sandbox is rendered by providing a third argument to the SandpackClient constructor.

Here’s an example:

const client = new SandpackClient(sandpackEl, {
  // files and dependencies
}, {
  showOpenInCodeSandbox: false,
  showErrorScreen: false,
  showLoadingScreen: false,
});

Updating the output

So far, we managed to create a static sandbox. That is, the output is rendered only once. If you want to create a sandbox with real-time updates, you’ll need to call client.updatePreview(info) with a new list of files, an entry point, and a list of dependencies every time your sandbox needs to be updated.

Styling

To style the sandbox container, you’ll need to apply CSS rules to the iframe element. Here’s an example:

#sandbox {
  width: 800px;
  height: 400px;
  border: 1px solid #aaa;
  border-radius: 8px;
}

To style the contents of the sandbox, you’ll need to inline them into your index.html file that you provided to SandpackClient or by providing a separate stylesheet.