Goals

I love turbo but, ironically, as one starts to rely on turbo more and more, the interaction between tasks defined in turbo and package.json scripts gets less and less ergonomic. (See background below.)

Prior to the introduction of turbo Package Configurations, reading a task's script from package.json was essential, as it was the only way for each package to customize the task's behavior. Now that Package Configurations exist, though, there's an opportunity to majorly simplify the interaction between turbo, the package manager, and their separate config files.

Non-goals

No response

Background

As a project leans on turbo more and more, here's what happens:

1. Many package.json scripts end up being of little use to run directly (i.e. without turbo), because they're written to assume that turbo will have already run the tasks they depend on. Someone trying to run the package.json script through their package manager would need to know all its dependencies, which are usually documented only in the turbo config and change over time. So these scripts live in package.json, but are really only useful to turbo.

2. Meanwhile, even for a package.json script that could be run effectively without turbo — because no turbo tasks depend on it, and it depends on no turbo tasks — it ends up being useful to add the script into turbo.json as a task with an empty task config (e.g., "some-leaf-task": {}). Doing that simplifies the developer's local workflow, because it lets them run everything through turbo — rather than having to run some tasks through turbo, some through their package manager, and having to keep track of tasks should be run in which way. Running even these leaf tasks through turbo is also more future-proof and makes for more stable docs, because, if the task later does need to depend on some task, developers won't have to change their workflows to start running the task through turbo instead of through their package manager.

3. Finally, some important turbo tasks end up without a corresponding script in package.json. For example, a package's dev task in turbo might be defined to run two commands in parallel (e.g. "with": ["a:watch", "b:watch"]), but there wouldn't be a "dev" script in package.json.

Given all this, a dev team can choose to always add every package.json script as a turbo task, and then always run all commands via turbo. However, that results in a lot of duplication/syncing between the two config files.

Alternatively, if not every script is added as a turbo task, devs must look in both package.json and turbo.json to see the full list of available tasks (point three above), and be prepared to switch which tasks they run through turbo and which tasks they don't as task dependencies evolve. (I.e., if a task is defined in turbo, always run it through turbo; otherwise, run the corresponding script through the package manager.)

Both options are a bit annoying.

Proposal

I propose adding a "command" key to each turbo task's definition; if present, turbo will run this key's command instead of any package.json script.

It would probably be ideal for the command to execute as though it were a package.json script being run by the package manager (i.e., so it would have access to binaries from installed packages, etc.), but I don't think this is necessary.

By adding such a key to a task's config, it should be possible for a package to remove all of its package.json scripts and simply rely on the package-specific turbo.json. turbo.json becomes a supercharged package.json that defines not just the scripts but also the graph information needed to orchestrate them.

Small example with my proposal:

// turbo.json
{ 
  "extends": ["//"],
  "tasks": {
    "local-services:start": { 
      "cache": false,
      "command": "docker .... --wait"
    },
    "db:migrate": {
      "dependsOn": ["local-services:start"],
      "command": "pnpm exec migrator apply --db api"
    },
    "lint:db:schemalint": {
      "dependsOn": ["db:migrate"],
      "command": "pnpm exec schemalint --config .schemalintrc.cjs"
    },
    "lint:db:squawk": {
        "inputs": ["migrations/*.sql"],
       "command": "pnpm exec squawk 'migrations/*.sql'"
    },
    "lint:eslint": { 
       "command": "pnpm exec eslint ."
    },
    "lint": { 
      "dependsOn": ["lint:db:schemalint", "lint:db:squawk", "lint:eslint"]
   }
}

Without this proposal, we'd have:

// turbo.json
{ 
  "extends": ["//"],
  "tasks": {
    "local-services:start": { 
      "cache": false 
    },
    "db:migrate": {
      "dependsOn": ["local-services:start"]
    },
    "lint:db:schemalint": {
      "dependsOn": ["db:migrate"]
    },
    "lint:db:squawk": {
        "inputs": ["migrations/*.sql"],
    },
    "lint:eslint": {},
    "lint": { 
      "dependsOn": ["lint:db:schemalint", "lint:db:squawk", "lint:eslint"]
   }
}

// package.json
{
  "scripts": {
    "local-services:start": "docker .... --wait",
    "db:migrate": "migrator apply --db api",
    "lint:db:schemalint": "schemalint --config .schemalintrc.cjs",
    "lint:db:squawk": "squawk 'migrations/*.sql'",
    "lint:eslint": "eslint ."
  }
}

As you can see, the solution without this proposal:

1. All the task/script names are duplicated, and splitting up the graph structure and the actual command being run arguably makes things a bit harder to follow and maintain.
2. turbo.json needs a dummy, empty task for lint:eslint.
3. The lint task doesn't have a package.json script; a developer can only discover it by also looking in turbo.json.
4. The db:migrate and lint:db:schemalint tasks exist in package.json, but can't actually be run successfully through the package manager alone unless the developer knows their (current) dependencies.

Assuming the root turbo.json can also define a task's "command", which would get inherited just like anything else, then this also solves the concerns about package.json script duplication that have been raised in prior discussions. But I see that as a bonus.

The biggest thing here, imo, is that devs shouldn't have to know when to run a task through turbo and when to use their package manager, and making everything runnable through turbo shouldn't require arbitrarily duplication.