Turbowatch

In Turbowatch, tasks can be categorized as either Persistent or Non-Persistent.

• Persistent Tasks: These are long-running processes that do not exit on their own, such as a development server (next dev) or a process in --watch mode. You must set persistent: true for these.
• Non-Persistent Tasks: These are tasks that run to completion (e.g., a build script like tsc).

Behavioral Difference: If a task is marked as persistent: false (the default), Turbowatch will ignore new FileChangeEvents if the current onChange routine is still executing and interruptible is set to false. This prevents overlapping executions of build scripts.

Turbowatch is designed to work alongside Turborepo. Since Turborepo does not currently support watch mode, you should use Turbowatch to handle the watching logic within a Turborepo task.

To integrate them:

1. Define a task in your package.json as persistent and disable cache.
2. Run the task using the --parallel flag in Turborepo.

Note on Dependencies: Avoid using Turborepo's dependsOn with Turbowatch, as it can produce undesirable effects. Instead, use Turbowatch expressions to identify when dependencies update. If your builds fail on the first attempt because Turbowatch is not aware of the Turborepo dependency graph, configure Turbowatch to watch node_modules; it will automatically retry failing builds once the dependencies are updated.

// package.json
"dev": {
  "cache": false,
  "persistent": true
}

// CLI
turbo run dev --parallel

Turbowatch uses the Roarr logger. To see logs in your terminal:

1. Set the ROARR_LOG=true environment variable.
2. (Optional) Pipe the output to @roarr/cli for pretty-printing.

ROARR_LOG=true turbowatch | roarr

Turbowatch is a fast file change detector and task orchestrator for Node.js. You can install it via npm and run it by providing a configuration file (e.g., turbowatch.ts) to the turbowatch executable.

Note: This project is deprecated. Consider using turbo watch or Tilt for new projects.

npm install turbowatch

# Create a configuration file
cat > turbowatch.ts <<'EOD'
import { defineConfig } from 'turbowatch';

export default defineConfig({
  project: __dirname,
  triggers: [
    {
      expression: ['match', '*.ts', 'basename'],
      name: 'build',
      onChange: async ({ spawn }) => {
        await spawn`tsc`;
      },
    },
  ],
});
EOD

# Run turbowatch
npm exec turbowatch ./turbowatch.ts

You can configure automatic retries for a trigger by providing a retry object. This is useful for flaky tasks or tasks that depend on external resources.

Retry Configuration Options:

• factor (number): The exponential factor to use. Default is 2.
• maxTimeout (number): The maximum number of milliseconds between two retries. Default is 30000.
• minTimeout (number): The number of milliseconds before starting the first retry. Default is 1000.
• retries (number): The maximum amount of times to retry the operation. Default is 3.

Turbowatch configuration scripts must export a Watcher function. This function is used by the CLI to initialize the watch process.

When creating a script, ensure you export a configuration object that includes a Watcher property which is a function. This function is expected to return a TurbowatchController (or be part of the configuration input used by the watch API).

// Example structure of a turbowatch script
export default {
  Watcher: async () => {
    // ... implementation
  }
};

Turbowatch uses an Expression type based on Watchman expressions to filter file changes. Supported operators include:

• ['allof', ...Expression[]]: True if all grouped expressions are true.
• ['anyof', ...Expression[]]: True if any grouped expression is true.
• ['not', Expression]: Inverts the sub-expression.
• ['match' | 'imatch', string]: Matches against the file basename.
• ['match' | 'imatch', string, 'basename' | 'wholename']: Matches against either the basename or the full path.
• ['dirname' | 'idirname', string]: True if the file has a matching parent directory.

// Example expressions
const matchAllTs = ['match', '*.ts'];
const matchAnyJsOrTs = ['anyof', ['match', '*.js'], ['match', '*.ts']];
const notMatchTxt = ['not', ['match', '*.txt']];

By default, Turbowatch throttles log output to at most once per second per task to prevent interleaved logs from multiple processes from becoming unreadable.

To disable this throttling and see all logs immediately (which may result in interleaved output), set the throttleOutput option with a delay of 0 in the watch configuration.

// Example of disabling throttling
void watch({
  throttleOutput: { delay: 0 },
  // ... other config
});

When working in monorepos or complex workspaces, you can watch both node_modules (for dependency changes) and src (for source changes). This example assumes source is in src and build output is in dist.

import { watch } from 'turbowatch';

void watch({
  project: path.resolve(__dirname, '../..'),
  triggers: [
    {
      expression: [
        'anyof',
        [
          'allof',
          ['dirname', 'node_modules'],
          ['dirname', 'dist'],
          ['match', '*', 'basename'],
        ],
        [
          'allof',
          ['not', ['dirname', 'node_modules']],
          ['dirname', 'src'],
          ['match', '*', 'basename'],
        ],
      ],
      name: 'build',
      onChange: async ({ spawn }) => {
        return spawn`pnpm run build`;
      },
    },
  ],
});