Repository Setup + Tips & Tricks

This guide will help you get started with using CodeSandbox for your repo. It's a walkthrough with a bunch of tips and tricks on how to get the most out of CodeSandbox!

Create a Team & Import a Repository

To get started with CodeSandbox for your repo, we recommend creating a team first. You can do this at the dashboard (opens in a new tab), by clicking on the workspace on the left, and pressing “Create a new team”. You can optionally start a free trial, in case you want better VM specs and import private repositories.

Once you've created the team, you can import a repository by clicking “Import from GitHub” and entering the URL of the GitHub repo. Once you've clicked “Import”, you're off to the races!

The first time when you import a repo, it can take a while. During first-time setup, we clone the repository into the VM and set up the folders for the project. However, after this setup, we will create a memory snapshot of the VM, which will ensure that all the following VM loads (& clones!) will be fast.

Next, let's take a look at the editor setup!

Editor & Workflow Setup

CodeSandbox has an opinionated flow when it comes to working with repositories, and you can see hints of this in the editor.

As soon as you enter the editor, you will see the current branch name in the header. Every branch has its own VM and is available through a unique URL. For example, if two people visit the URL for the main branch, they will be able to see each other's cursor, terminals and DevTools.

Now it's time to write some code!

Branching Workflow

On CodeSandbox, the main branch is protected by default. This means that it's read-only and will sync automatically with the branch on GitHub when new commits come in.

To write some code, you have three options:

1. (Recommended) Just start typing some code - we will create a new branch for you using seamless branching!
2. Click the “Branch” button in the header.
3. Toggle protection off for the main branch.

Give it a try on the repository you imported!

When we create the new branch, we create a clone of the main VM and switch it to the new branch. This new VM is an exact copy of the original VM, down to the memory contents. Because of this, processes like dev servers are already started in the cloned VM.

As you can see, we automatically generated a new branch for you, starting with draft/.... This branch is not protected, so you can make changes, open terminals or open any other DevTool.

Git Workflow

When you're ready to open a PR, you can either click “Create PR” in the header or commit from the Git panel in the sidebar.

Next, let's do some configuration to make your repository work in CodeSandbox.

Environment Configuration

Generally, we recommend configuring the environment with a Dockerfile. When Docker is enabled, any new terminal will open inside a container and you will have root access to install additional packages.

To enable the Docker integration, you need to create a folder called .codesandbox in the root of your repo and put a file named Dockerfile in there. An example Dockerfile could look like this:

FROM node:18.14.0-bullseye
 
# Install htop
RUN apt update -y && apt install -y htop

This will ensure that Node.js is installed, but you can make any changes to this Dockerfile to install additional language support or packages.

After you've made changes to the Dockerfile, you should see a notification that prompts you to rebuild the containers. Press “Yes” and you'll see the setup tasks start again, with a new entry to build the image. The built image is cached and available through VM cloning in other branches.

You don't have to mount or ADD any files from your workspace folder. We'll make sure that your repository is mounted at /workspace when we start the container.

If you would like to learn more about how our Docker integration works, we recommend checking out Docker Integration.

Task Configuration

You can use tasks to configure what terminal commands should run by default, and what terminal commands need to run when the VM boots, or when a certain event happens.

To create a task configuration, open the command palette by typing ⌘/Ctrl + Shift + P. Then choose “Create task configuration”.

There are two fields in this file:

• setupTasks: these tasks are run when the VM boots or when a new commit comes in on a protected branch (like main).
• tasks: these tasks are available through DevTools and are the recommended way of configuring commands to start development servers or build tasks.

An example configuration could look like this:

{
  "$schema": "https://codesandbox.io/schemas/tasks.json",
  "setupTasks": [
    {
      "name": "Installing Dependencies",
      "command": "pnpm install"
    }
  ],
  "tasks": {
    "dev": {
      "name": "Application",
      "command": "pnpm dev:v2",
      "runAtStart": true,
      "restartOn": {
        "files": ["pnpm-lock.yaml"]
      },
      "preview": {
        "port": 4000,
        "pr-link": "direct"
      }
    },
    "tests": {
      "name": "Run Tests",
      "command": "pnpm test"
    }
  }
}

This configuration says that:

• We should run pnpm install during setup.
• We should run pnpm dev:v2 when setup has been completed.
  • In case pnpm-lock.yaml changes, restart this task.
  • When a new PR opens, make a deployment for port 4000 and put it in the pull request.
• There's a task available to run tests, which anyone can click to run tests.

By making these changes, you'll ensure that the environment works by default. Other developers won't have to figure out what setup to do, or what commands to run to get started.

Configuring Secrets

Several repositories require setting environment variables—either to connect to an external service or as the configuration of the environment itself.

CodeSandbox allows you to set environment variables by clicking on our logo in the top left corner, and clicking on "Project Settings" and then “Env Variables”.

These environment variables will be encrypted and stored in our database. After you've set the environment variables, they will be available for any branch in the repository after a restart.

You can learn more about our environment variable support under Secrets.

VS Code Configuration

CodeSandbox supports opening branches in VS Code (opens in a new tab) and in our native iOS app (opens in a new tab). When you open the branch inside VS Code, you will have access to your own extensions, keybindings and themes.

If you want to configure default VS Code extensions to be installed for your repository, you can create a new file called .vscode/recommendations.json.

This is an example of how this file could look like:

{
  "recommendations": ["esbenp.prettier-vscode", "dbaeumer.vscode-eslint"]
}

When someone opens this VM in VS Code, we'll make sure that the extensions are preinstalled.

If you want to have some personal extensions available in any CodeSandbox branch, you can update your own VS Code settings to reflect this. In your VS Code settings (we recommend opening the JSON version by clicking on the File icon in the top left), you can add these settings, for example, to automatically install these extensions when connecting to a VM:

  "remote.SSH.defaultExtensions": [
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "GitHub.vscode-pull-request-github",
    "GitHub.copilot",
    "eamodio.gitlens"
  ]

Deployment Previews & GitHub App

Now that you've configured your repository to work in CodeSandbox, we highly recommend that you also configure deployment previews.

With deployment previews, CodeSandbox automatically adds a link to every PR you open, allowing anyone with access to the repo to open the PR on a preloaded development environment running in CodeSandbox. This is great for reviewing changes, testing the application, or quickly making changes to a PR.

To enable deployment previews, you need to install the CodeSandbox GitHub App. You can do this by opening the command palette (⌘/Ctrl + Shift + P) and selecting “Install GitHub App”.

After you've gone through the install steps, you should automatically get deployments for new PRs with a link to both the preview (if configured through tasks) and the development environment!

There are more advantages to using the CodeSandbox GitHub App, like automatic dashboard syncing. You can learn more about this under GitHub App.

Troubleshooting

Permission errors while importing a project

• Verify your team's permission to open CodeSandbox Repositories.

• Verify your repository permissions on GitHub. You need to have write permission on GitHub to be able to import the project. Repositories where you only have read access can only be forked.

• Verify your GitHub permissions. CodeSandbox requires full git access to be able to import and commit. If you face any authentication errors, follow the steps listed below to reset your GitHub permissions.

Resetting GitHub permissions

1. Go to the Dashboard (opens in a new tab).

2. Click on the Menu icon at the top right of the screen.

3. Click on Preferences.

4. Go to Integrations.

5. Sign out from GitHub and sign in again to reconnect your GitHub account.

Invalid authorization code on Firefox and Safari

Safari and Firefox block popups by default. Please make sure you give the domain permission (through the browser settings) or refresh the page after you opened the popup and try again.