# 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 Sandboxes and repositories.

## Default configuration [Permalink for this section](/content/docs/learn/vm-sandboxes/task#default-configuration/index.html)

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 [Permalink for this section](/content/docs/learn/vm-sandboxes/task#adding-and-configuring-tasks/index.html)

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.

💡

Checking these files into a repository's version control is recommended to ensure that every collaborator has a similar editing experience. This configuration can be tracked and additional changes can be made to specific branches. In addition, once the file is merged into your main branch, every new branch will follow the same configuration.

### Setup tasks [Permalink for this section](/content/docs/learn/vm-sandboxes/task#setup-tasks/index.html)

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 [Permalink for this section](/content/docs/learn/vm-sandboxes/task#configuring-task-ports/index.html)

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](/content/docs/learn/integrations/github-app/index.html) 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",
      "preview": {
        "port": 4000,
        "prLink": "direct"
      }
    }
  }
}
```

## Manually running, stopping and restarting tasks [Permalink for this section](/content/docs/learn/vm-sandboxes/task#manually-running-stopping-and-restarting-tasks/index.html)

The [DevTools](/content/docs/learn/vm-sandboxes/devtools/index.html) 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 [Permalink for this section](/content/docs/learn/vm-sandboxes/task#examples/index.html)

### Single page application [Permalink for this section](/content/docs/learn/vm-sandboxes/task#single-page-application/index.html)

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

### Mono-repo with multiple front-ends [Permalink for this section](/content/docs/learn/vm-sandboxes/task#mono-repo-with-multiple-front-ends/index.html)

```
{
  "$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 [Permalink for this section](/content/docs/learn/vm-sandboxes/task#reference/index.html)

- [JSON Schema for `tasks.json` (opens in a new tab)](/content/schemas/tasks.json)