Synced Templates

What are synced templates?

Synced templates are templates (opens in a new tab) that are created from a GitHub repository, or a folder in a GitHub repository. A synced template stays in sync with its source, so when you create a commit in the GitHub repository, the template will automatically update on next access with the new contents.

How is a synced template different from CodeSandbox Repositories?

CodeSandbox also has Repositories (opens in a new tab), which are also imported from GitHub repositories. However, there is a key difference between synced templates and repositories.

Repositories are meant for working on a repository. We introduce a workflow to create new branches and pull requests. Synced templates are meant to create a sandbox template from a repository (or folder), and are meant for using as template for new sandboxes (or for sharing as example with others).

A good rule of thumb is that if you want to work on a repository, you should import a repository. If you want to create a template from a repository, you should create a synced template from a GitHub repository.

Creating a synced template

A synced template URL is essentially the same as the GitHub URL, but github.com is replaced with codesandbox.io/s/github. Because of this, you can go to your GitHub repository, and replace github.com with codesandbox.io/s/github to create a synced template. We have also introduced three helpers to do this more easily:

https://codesandbox.io/s/github/withastro/astro/main/examples/blog (opens in a new tab)

Directly from the GitHub URL

First, visit the GitHub repository or folder that you want to create a synced template from. The URL should look something like https://github.com/owner/repo for a repository, and it should look like https://github.com/owner/repo/tree/main/folder for a folder.

Then, replace github.com with githubbox.com and press Enter.

This will redirect you to a URL that looks like https://codesandbox.io/s/github/owner/repo or https://codesandbox.io/s/github/owner/repo/tree/main/folder, which is the location of the newly created synced template!

Using our GitHub importer

Go to our "New Sandbox" modal (opens in a new tab) and click on the "Import template" button. Enter the GitHub URL you want to import in the input field and press "Open URL". This will redirect you to the location of the synced template.

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.

Configuring a title, icon & description

By default, we try to infer the name, description and icon of a synced template based on the files in the repository. However, you can also configure this manually.

You can configure a title, description and template icon for your synced template in a file called .codesandbox/template.json in your synced template. This file is a JSON file that contains the following properties:

• title: The title of the template
• description: The description of the template
• iconUrl: The icon of the template. This should be a URL to a 64x64 PNG or JPEG image.
• tags: The tags that will be used for search results. This should be an array of strings.
• published: Whether the template is published. If this is set to false, the template will not be visible in the template search.

An example template.json could look like this:

// .codesandbox/template.json
{
  "title": "My Template",
  "description": "This is my template",
  "iconUrl": "https://example.com/icon.png",
  "tags": ["react", "typescript"],
  "published": true
}

All fields are optional, we will infer the missing fields from the repository contents.

After you've created this file, and opened the synced template at least once, you can find it in the template search (opens in a new tab) by searching for the title or description.

VM behaviour of synced templates

For our cloud sandboxes (opens in a new tab), we run your sandbox in a microVM. We try to automatically detect from your repository contents whether your project is more suited for a cloud sandbox than a browser sandbox. To force the template to load as a cloud sandbox, you can create a .codesandbox/Dockerfile file in your repository. This file should contain a valid Dockerfile that we'll use to build your cloud sandbox.

We use memory snapshotting to resume a VM quickly when someone visits it. To ensure that visitors of your sandbox will always get the latest contents of your GitHub repository, we base the memory snapshot on the latest commit of your repository or folder.

This means that if you create a new commit in your repository, we will discard the memory snapshot of the synced template and will start the sandbox from scratch on next visit. During boot of the VM, we will download the latest file contents from the repository. This ensures that visitors of your sandbox will always get the latest contents of your GitHub repository, but it also means that the first visit of your sandbox after a commit can be slower than usual (only for memory, we do still keep the filesystem between invalidations).