Task

Tasks allow you to define commands (like yarn start) that can run at specific moments, such as during the project's setup, at a VM's startup, or when they are manually run. These tasks are shared between all the clients connected to the project where they're configured.

You can use tasks for multiple purposes. The most common ones include:

• installing the project's dependencies at the VM's startup.
• running a preview.
• running a linter.
• running tests.

Note that tasks are only supported in our VM environments (Devboxes and repositories).

Default configuration

By default, CodeSandbox tries to infer scripts from the package.json file in your project's root folder. In addition, you can always use the Environment setup DevTool to set any shell script to run your projects.

Adding and configuring tasks

Tasks are specified in the .codesandbox/tasks.json configuration file in your project. Below is an example of a configuration:

{
  "$schema": "https://codesandbox.io/schemas/tasks.json",
  "setupTasks": ["yarn install", "yarn build"],
  "tasks": {
    "install-dependencies": {
      "name": "Install Dependencies",
      "command": "yarn install"
    },
    "start-app": {
      "name": "Run Dev Server",
      "command": "yarn start",
      "runAtStart": true
    }
  }
}

To add a new task, create a new entry in the tasks array as exemplified above.

Setup tasks

Setup tasks are an array of commands that will run sequentially before the workspace is ready to start your application. If no value is provided, installing dependencies will be the default task (CodeSandbox will detect which package manager you use).

{
  "$schema": "https://codesandbox.io/schemas/tasks.json",
  "setupTasks": [
    {
      "name": "Installing Dependencies",
      "command": "yarn install"
    },
    {
      "name": "Building Workspace",
      "command": "yarn build"
    }
  ]
}

Configuring task ports

You can assign ports to tasks. Normally we try to automatically detect ports assigned to a task, but there are three advantages to defining them manually using the preview field:

1. We'll automatically eagerly a preview for this port when opening the project.
2. If the port is not opened, and you try to open it using our preview, we give the option to open the task assigned to the port.
3. The GitHub App will automatically add the link to the preview in a comment for every pull request, and we'll create deployments for them.

The preview object has two fields: port and optional prLink. The port field defines the port that this task opens, and the prLink defines how PRs should link to this port. The possible options are direct and devtool.

With direct, you will directly open the preview URL from the PR.

With devtool, you will open the preview URL with an experimental devtool inside the preview.

Here's an example:

{
  "$schema": "https://codesandbox.io/schemas/tasks.json",
  "tasks": {
    "dev-server": {
      "name": "Start Dev Server",
      "command": "yarn dev",
      // With the `preview` field set, the GitHub App will also add a link
      // to that preview to PRs, and it will become part of a GitHub
      // deployment:
      "preview": {
        "port": 4000,
        // This next field is optional:
        "prLink": "direct"
      }
    }
  }
}

Manually running, stopping and restarting tasks

The DevTools panel lists all tasks and allows you to manually run, stop and restart a task (these options are shown when you hover any given task from the displayed list).

Examples

Single page application

{
  "$schema": "https://codesandbox.io/schemas/tasks.json",
  "tasks": {
    "run-dev": {
      "name": "App",
      "command": "yarn run dev",
      "runAtStart": true
    }
  }
}

Mono-repo with multiple front-ends

{
  "$schema": "https://codesandbox.io/schemas/tasks.json",
  "tasks":{
    "build":{
      "name":"Build Workspace",
      "command":"yarn build:workspace"
    },
    "homepage":{
      "name":"Homepage",
      "command":"yarn workspace homepage dev",
      "runAtStart":true
    },
    "docs":{
      "name":"Docs",
      "command":"yarn workspace docs dev"
    },
    "admin":{
      "name":"Admin",
      "command":"yarn workspace admin dev"
    },
    "dashboard":{
      "name":"Dashboard",
      "command":"yarn workspace dashboard dev"
    }
  }
}

Reference

• JSON Schema for tasks.json (opens in a new tab)