Getting Started with Sandboxes

Finding Sandbox Templates

The most popular way of creating a new Sandbox is the 'New' modal.

The New modal shows you collections of templates grouped first by relevance and then by broad category. This list is not comprehensive of all the Sandboxes that have been made by the community, however. If you want to browse other Sandboxes and Templates, you can explore everything in through the discover button at the bottom of the dashboard sidebar.

Templates are automatically forked when you select them, so you can edit and begin creating your own sandbox.

Using GitHubBox.com

An easy way to import a repo to CodeSandbox via URL is with GitHubBox.com. Append 'box' to your github.com URL in between 'hub' and '.com' and it will redirect to CodeSandbox.

Here's an example:

Change the GitHub URL: https://github.com/reduxjs/redux/tree/master/examples/todomvc (opens in a new tab).

To: https://githubbox.com/reduxjs/redux/tree/master/examples/todomvc (opens in a new tab).

The result is we take the last part of the url (everything after github.com) and use it in our importer at codesandbox.io/s/github/, adding the repo to CodeSandbox.

Using a Browser Extension

We have browser extensions for Chrome (opens in a new tab) and Firefox (opens in a new tab), which add an 'Open in CodeSandbox' button to GitHub repo pages. This makes it easy to import existing projects from GitHub in to CodeSandbox.

Setting inference

When importting, we infer sandbox settings based on several files in a repository.

If the correct template isn't automatically being used when importing, then you may specify a template property in your ./sandbox.config.json file to override the detected template.

{
  "template": "node"
}

Import Local projects via CLI

You can import a local project in to CodeSandbox by using our CLI (opens in a new tab).

You can install our CLI by running npm install -g codesandbox. Then import a project by running codesandbox {directory}.

Example usage

$ npm install -g codesandbox
$ codesandbox ./

Define API

We offer an API that allows you to programmatically create a sandbox. This is useful for documentation, enabling you to generate a sandbox on the fly from code examples. You can call the endpoint https://codesandbox.io/api/v1/sandboxes/define both with a GET and with a POST request.

Supported Parameters

We currently support three extra parameters. The query accepts the same options as the embed options.

How it works

The API only needs one argument: files. This argument contains the files that will be in the sandbox, an example body would be:

{
  "files": {
    "index.js": {
      "content": "console.log('hello!')",
      "isBinary": false
    },
    "package.json": {
      "content": {
        "dependencies": {}
      }
    }
  }
}

Binary Files

You can import binary files by setting isBinary to true and content as a URL to the file hosted externally. For example:

{
  "isBinary": true,
  "content": "https://..."
}

Folders

You can create folders by naming the file with a / in it's name, allowing to structure your application how you want:

{
  "files": {
    "src/index.js": {
      "content": "console.log('hello!')",
      "isBinary": false
    },
    "package.json": {
      "content": {
        "dependencies": {}
      }
    }
  }
}

This will create a file called index.js in your src folder.

Package.json

Every request requires a package.json. This file can either be a string or an object. We determine all information of the sandbox from the files, like we do with the GitHub import.

GET Request

It's very hard to send the JSON parameters with a GET request, there is a chance of unescaped characters and the URL hits its limit of ~2000 characters quickly. That's why we first compress the files to a compressed lz-string. We offer a utility function in the codesandbox dependency for this. The implementation looks like this:

import { getParameters } from 'codesandbox/lib/api/define';
 
const parameters = getParameters({
  files: {
    'index.js': {
      content: "console.log('hello')",
    },
    'package.json': {
      content: { dependencies: {} },
    },
  },
});
 
const url = `https://codesandbox.io/api/v1/sandboxes/define?parameters=${parameters}`;

Example Sandbox

https://codesandbox.io/s/6yznjvl7nw?editorsize=50&fontsize=14&hidenavigation=1&runonclick=1 (opens in a new tab)

POST Form

You can do the exact same steps for a POST request, but instead of a URL you'd show a form. With a POST request you can create bigger sandboxes.

Example Sandbox

https://codesandbox.io/s/qzlp7nw34q?editorsize=70&fontsize=14&hidenavigation=1&runonclick=1 (opens in a new tab)

Define without render

If you want to define a new sandbox without getting it rendered, you can add ?json=1 to the request. For instance https://codesandbox.io/api/v1/sandboxes/define?json=1. Instead of the render, the result will be json data providing you with the sandbox_id of the new sandbox.

This is useful, for instance, if you need to create a new sandbox programmatically, so you can then embed it on your site (See Embed documentation).

Both get and post requests are supported.

XHR Request

You can also create a sandbox using an XHR request, like using fetch. An example sandbox of that is here:

https://codesandbox.io/s/9loovqj5oy?editorsize=70&fontsize=14&hidenavigation=1&runonclick=1 (opens in a new tab)

Import Single Components

You can import a local component in to CodeSandbox by using our other CLI (opens in a new tab).

You can install our CLI by running npm install -g codesandboxer-fs. Then you can export a project by running codesandboxer {filePath}.

$ npm install -g codesandboxer-fs
$ codesandboxer docs/examples/my-single-component.js

This will print out the id of a sandbox that does nothing but render the targeted component, along with a link to that sandbox. This will also bundle in other local files used by the component to ensure render.

Import Using Codesandboxer

Codesandboxer (opens in a new tab) imports a single file from a git repository, along with supplemental files and dependencies. Using this creates an easy way to upload an example instead of an entire git repository. This enables you to easily share examples with others, or to link to editable versions of examples from a documentation website. React-codesandboxer is the main version, but there are also versions for VS Code, Atom, and BitBucket.

How it works

Below the surface, react-codesandboxer fetches the files it needs from GitHub or BitBucket, using a single file that will be rendered as the 'example' as an entry point, then uses the Define API to upload the necessary files into a new create-react-app sandbox.

Check out the codesandboxer docs (opens in a new tab) for information on how to implement it.

import React, { Component } from 'react';
import CodeSandboxer from 'react-codesandboxer';
 
export default () => (
  <CodeSandboxer
    examplePath="examples/file.js"
    gitInfo={{
      account: 'noviny',
      repository: 'react-codesandboxer',
      host: 'github',
    }}
  >
    {() => <button type="submit">Upload to CodeSandbox</button>}
  </CodeSandboxer>
);

Import Using Remark-codesandbox

Remark-codesandbox (opens in a new tab) is a remark plugin for creating sandboxes directly from code blocks in documentation. Developed by CodeSandbox community member Kai Hao, it supports popular platforms including MDX, Gatsby, Storybook Docs, docz etc. Learn more about it in their documentation (opens in a new tab).