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.
Because synced templates stay in sync with its source, you can't edit a synced template in CodeSandbox. If you want to edit the template, you'll have to commit to the source repository. You could consider that GitHub is the "owner" of the template.
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 templatedescription
: The description of the templateiconUrl
: 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 tofalse
, 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).