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 with the new contents on the next access.

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 allow you to create a Devbox/Sandbox template from a repository (or folder), and are meant to be used as a template for new projects (or for sharing as an 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 runs code from a GitHub branch in CodeSandbox and keeps the changes synced with remote. A synced template can either be a Sandbox or a Devbox. You can tell the difference by the way the URL is constructed:

• A synced template as a Devbox will look something like this: codesandbox.io/p/devbox/github.
• A synced template as a Sandbox will look something like this: codesandbox.io/p/sandbox/github.

As explained below, you can create synced templates directly from the GitHub URL or through our GitHub importer tool.

Directly from the GitHub URL

First, visit the GitHub repository or folder from which you want to create a synced template. The URL should look like https://github.com/owner/repo for a repository and 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/p/devbox/github/owner/repo or https://codesandbox.io/p/devbox/github/owner/repo/tree/main/folder, which is the location of the newly created synced template!

Using our GitHub importer

Go to our "Repo Import" modal (opens in a new tab) and click on "Import template". 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 into CodeSandbox.

Configuring a title, icon & description

By default, we try to infer a synced template's name, description and icon 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 behavior of synced templates

We try to automatically detect from your repository contents whether your project is more suited for a Devbox (which runs in a VM) than a Sandbox (which runs on the browser).

To force the template to load as a Devbox, you can create a .devcontainer/devcontainer.json file in your repository. This file should contain a valid Dev Container configuration (opens in a new tab) that we'll use to build your Devbox.

We use memory snapshotting to resume a VM quickly when someone visits it. To ensure that visitors of your Devbox 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 Devbox from scratch on next visit. During the VM boot, we will download the latest file contents from the repository. This ensures that visitors to your Devbox will always get the latest contents of your GitHub repository, but it also means that the first visit of your Devbox after a commit can be slower than usual (only for memory; we do still keep the filesystem between invalidations).