A belated introduction to Codesandboxer

codesandbox is a very cool tool. It allows you to manage your code through an online editor, and easily share it with others. The ability to do this opens up a host of possibilities for us.

For example: Wouldn’t it be cool if there was a button on your website, where you could open an example in an editable sandbox? We thought that would be cool, so we built it into the Atlaskit website with a simple button:

And here’s the sandbox that button generates embedded in medium. Go ahead and experiment with changing its props.

Being able to do this has three main benefits:

It helps people try our components

This is the really obvious one, but by letting people open one of our examples on their own, the barrier to recreate your use-case is a lot lower.

It helps people report bugs

This one is a bit more subtle, but has probably been the most important. When someone is reporting to us on one of our components, with a bug or a feature request, seeing it in a sandbox allows us to immediately go ‘oh yeah, we super need to fix that, or ‘ah, you need to use this prop instead. We’ll update our documentation’ or even ‘that is a feature that we have deliberately not added because of this other thing, let me show you’ with incredible ease. Making it super easy to get started on a sandbox has made it easier to make this part of how we work with other teams.

It helps us share changes we are looking to make with people

This one is the one that excites me the most. As we build our components, we want to start getting feedback on changes as early as possible. It has made collaboration easier. We can now spin up a sandbox, and send it out to those interest, and get feedback on how it runs before a PR, and well before code is published to NPM.

We just ran into one problem in what we wanted verse how codesandbox thinks about code.

Codesandbox uses a project as its base model (for our purposes, a create-react-app project). By working on a project scope, it assumes that everything you are writing will be a react project. Its core model to upload something to codesandbox is to upload the entire git repo, and assume its entry file runs an app.

All that we wanted was to be able to give it a component, rather than a whole repository. To do that we built:

Codesandboxer

codesandboxer allows you to get any component you have written anywhere and put it on codesandbox

This is great, because now we can target anything that is a ‘component’ and upload it, no hassle.

Some of the clever things codesandboxer does for you in uploading an example:

• It follows relative imports to include files (but checks if a file is already included before adding it again)
• It uses your package.json to get versions for external dependencies
• It provides base files that run the passed in file as a react component
• You can provide your own files directly, which can override the base files

How do I use it?

codesandboxer encapsulates a core logic of how to analyze and bundle files from an entry point, placing those files into codesandbox. This originally started as a react component itself, however the core logic was extracted away from this into the codesandboxer package. Since doing this, I’ve found a bunch of other cool ways to extend this process.

You can sandbox from your site

react-codesandboxer, the origin point of this journey, is a react component which accepts git info (username, repository, branch, and git source), as well as a path to an example relative to the repository’s route directory. It then goes and fetches the raw files needed from github or bitbucket, and opens a link out to a sandbox of the example file.

This was originally built for atlaskit’s examples, and we’ve extended it to a couple of other sites with examples.

Cool note, because we are doing this from the website itself, we can do the absolute minimum effort up front. Only once the button is clicked do we bundle files, and only once we have a valid bundle of files do we hit codesandbox.

Codesandboxer was extracted out of this, but still fundamentally is being rendered in the client, and always looks towards github or bitbucket as the file location, however…

You can sandbox from command line

Having gotten sandboxes from examples on the website, I kept wanting to open a local example (or a local set of code changes) in codesandbox, to share with people either when one of us was working from home, or when I was working at an odd hour. With the logic already written, and pulled out into its own package, I took a hack day to see if I could get this working.

$ npm install — global codesandboxer-fs
$ codesandboxer some/file/path.js

This command finds the first package.json above the target file, and uses that as its root. It pulls files from your local directory, but is otherwise doing the same work as codesandboxer, bundling up the dependencies you need, and returning a link to your new sandbox.

This is great for sharing changes to prototype quickly, and even allowing someone else to suggest changes through code.

With this done, I took the obvious next step:

You can sandbox from and IDE

I built a vs-code plugin and an atom plugin that sits on top of codesandboxer-fs, so that you can right click in your javascript file and deploy it directly to codesandbox.

Where else can you sandbox? We shall see

One of the things I am happiest with about this project is that the two underlying logic packages codesandboxer and codesandboxer-fs, there is ground for other people to expand on these, and use the core concept in new ways to enhance their own workflows.

It is also built in to docz playgrounds.

Is this going to keep changing?

There’s a bunch of different directions codesandboxer could be extended in. Some quick low-hanging fruit we are looking at is:

• supporting other kinds of sandbox (vue, parcel)
• fetching babel configs (and their dependencies) alongside the files
• Being smarter with importing different file types

If you have questions, yell politely at me on twitter or checkout out the project on github.