SDK
Setup

Setup

Setup tasks are configured in your project's .codesandbox/tasks.json file. This file defines both setup tasks that run when the sandbox starts, and regular tasks that can be run on-demand.

Setup tasks run in order when initializing your sandbox. They're typically used for installation and preparation steps:

{
  "setupTasks": [
    {
      "name": "Install Dependencies",
      "command": "pnpm install"
    },
    {
      "name": "Copy Environment File",
      "command": "cp .env.example .env"
    },
    "pnpm run build"  // Short form for { "name": "pnpm run build", "command": "pnpm run build" }
  ]
}

API

Setup tasks run automatically when a sandbox starts. They typically handle installation of dependencies and initial builds. You can monitor and control setup tasks using the Setup API:

const sandbox = await sdk.sandboxes.create()
const session = await sandbox.connect()
 
console.log(`Setup status: ${session.setup.status}`);
 
// Wait for the whole thing to complete
await session.setup.waitUntilComplete()
 
// Or handle each step
const steps = await session.setup.getSteps()
 
for (const step of steps) {
  console.log(`Step: ${step.name}`);
  console.log(`Command: ${step.command}`);
  console.log(`Status: ${step.status}`);
 
  const output = await step.open()
 
  output.onOutput((output) => {
    console.log(output)
  })
 
  await step.waitUntilComplete()
}

Setup Tasks vs Docker Build: When to Use Which?

Setup tasks are used for any preparation work needed in the /project/sandbox directory, such as:

  • Installing dependencies
  • Building assets
  • Running initial compilations

Docker build, on the other hand, should be used for:

  • Setting up the container environment
  • Installing system-level dependencies
  • Configuring global tools

This separation exists because the /project/sandbox directory is only available after the container starts.

TasksGit