turbo watch

The watch command is the reference entry point for rerunning Turborepo tasks after files change. It is meant for development loops where a developer wants the same dependency-aware task ordering used by normal task execution, but without repeatedly invoking the command by hand. The public docs describe the command as a way to re-run tasks in a repository based on code changes, using the task graph configured in the workspace. That makes it most useful for feedback-oriented tasks such as builds, type checks, tests, code generation, or any nonpersistent script that should react when a package changes.

Sources: apps/docs/content/docs/reference/watch.mdx

Purpose and Scope

Use the watch command when the file system is the trigger and the task graph is still the source of truth. A monorepo often has many packages, and a change in one package can require rebuilding or retesting consumers. Turborepo already knows those relationships through package dependencies and task definitions, so watch mode preserves that ordering instead of treating every script as an isolated shell command. The command accepts task names, watches for relevant changes, and reruns the selected work as those changes arrive.

Sources: apps/docs/content/docs/reference/watch.mdx

This page is a command reference, so it focuses on observable behavior, configuration touchpoints, and practical constraints rather than a complete walkthrough of every project shape. The important distinction is that watch mode is not a replacement for every framework development server. If a tool already has a dependency-aware watcher, such as a framework dev command that can reload dependency modules correctly, Turborepo recommends using that tool directly and marking the corresponding task as long-running in configuration. Watch mode is most valuable when Turborepo needs to coordinate reruns across package boundaries.

Sources: apps/docs/content/docs/reference/watch.mdx

Relevant Source Files

• apps/docs/content/docs/reference/watch.mdx — The first-party reference for command syntax, dependency awareness, default package-level change handling, task-input filtering, persistent task behavior, experimental cache writing, and task-output limitations.
• crates/turborepo-filewatch/Cargo.toml — The Rust crate manifest for the repository file watching layer, showing dependencies on file notification, asynchronous runtime, repository metadata, source-control utilities, path handling, directory walking, and optional macOS file system events support.
• crates/turborepo-globwatch/Cargo.toml — The Rust crate manifest for the glob-oriented watch layer, showing the crate named globwatch, its description as efficient glob watching, and dependencies for notifications, stream merging, stop tokens, asynchronous streams, tracing, and path handling.

Command Syntax and Default Behavior

The command form is simple: pass one or more task names after the watch command. When no tasks are passed, Turborepo does not silently watch everything; the documented behavior is to display the tasks available for packages in the repository. That makes an empty invocation useful as a discovery step when entering an unfamiliar workspace. Once task names are supplied, watch mode uses the configured task graph, so dependent work runs in the configured order rather than in the arbitrary order that file system events happen to arrive.

Sources: apps/docs/content/docs/reference/watch.mdx

turbo watch [tasks]

turbo watch

By default, watch mode operates at the package level. That phrase means that a file change anywhere inside a package causes all watched tasks for that package to rerun, even if the changed file is not part of a particular task input set. This default is conservative and easy to reason about: a package changed, so the package’s requested tasks are refreshed. For teams with larger packages or many narrowly scoped tasks, the docs identify a more precise mode through the future flag for task input watching, which narrows file relevance according to each task’s input globs.

Sources: apps/docs/content/docs/reference/watch.mdx

The task-input mode is important because Turborepo configuration can define inputs for each task. Inputs describe the files that participate in hashing and task relevance. When the future flag for watching task inputs is enabled, watch mode can filter at the task level rather than only at the package level. In practice, this means a documentation file might avoid retriggering a build task if that build task’s input globs do not include it, while a source file covered by the inputs still causes the task to rerun.

Sources: apps/docs/content/docs/reference/watch.mdx

Dependency-Aware Reruns

The central behavior to understand is dependency-aware rerunning. The docs state that watch mode reruns tasks in the order configured in the workspace configuration. In Turborepo terms, tasks are not just named scripts; they can have dependencies on other tasks, including package dependency relationships. When a change affects a package, watch mode uses that graph to determine the sequence of reruns. This helps prevent consumers from rebuilding against stale upstream outputs and keeps watch behavior aligned with normal task execution.

Sources: apps/docs/content/docs/reference/watch.mdx

A good mental model is to treat watch mode as repeated graph execution, not as a raw file watcher that launches commands immediately. File changes provide the signal, and the configured graph provides the plan. This is particularly useful in workspaces where one package builds shared code and another package consumes it. If the shared package changes, Turborepo can run the necessary upstream work before downstream tasks that depend on those outputs. The result is a development loop that respects repository structure instead of only responding to the nearest changed file.

Sources: apps/docs/content/docs/reference/watch.mdx

The manifests for the Rust watch-related crates show how this command family is backed by dedicated infrastructure rather than ad hoc polling in documentation code. The file watching crate depends on notification, asynchronous execution, repository metadata, source-control utilities, path handling, directory walking, tracing, and glob matching support. The globwatch crate is described as watching a set of globs efficiently and depends on notification, stream utilities, stop tokens, asynchronous streams, Unicode segmentation, tracing, and path handling. These manifests define the implementation boundaries visible in the supplied source.

Sources: crates/turborepo-filewatch/Cargo.toml, crates/turborepo-globwatch/Cargo.toml

Persistent Tasks and Development Servers

Persistent tasks are long-running tasks marked in configuration as persistent. The docs define them as tasks that do not exit, which means they cannot be depended on in the task graph. This matters because graph execution needs tasks to complete before dependent tasks can proceed. A task such as a development server may keep running forever, so Turborepo treats it differently from a build or test command. Watch mode follows the same approach as normal task execution by ignoring persistent tasks, allowing persistent and nonpersistent tasks to coexist without blocking the graph.

Sources: apps/docs/content/docs/reference/watch.mdx

When a persistent task already has dependency awareness built in, the recommended workflow is not to wrap it in watch mode. For example, a framework development server that can detect changes in dependent packages and hot reload correctly should be run as its own persistent task. In that setup, the script’s watcher owns the live reload behavior, while Turborepo configuration marks the task as long-running. This avoids duplicating watcher logic and prevents the repository-level watch command from fighting a tool that already understands how to refresh itself.

Sources: apps/docs/content/docs/reference/watch.mdx

Some tools are long-running but not monorepo-friendly. They may watch the application package but fail to reload modules from internal dependencies. The docs recommend marking that kind of task as interruptible so Turborepo can restart it when relevant changes are detected. This creates a practical middle ground: the task remains a development process, but Turborepo is allowed to stop and restart it when dependency changes require a fresh process. Use this option when the tool’s own watcher is insufficient for workspace dependency changes.

Sources: apps/docs/content/docs/reference/watch.mdx

Caching and Task Output Limitations

Caching in watch mode is explicitly marked experimental in the reference page. The documented opt-in flag writes cache artifacts while watch mode is running. Without relying on undocumented internals, the safest interpretation is that teams should treat watch cache writes as a feature to evaluate deliberately rather than a baseline production assumption. Normal cache semantics are central to Turborepo, but a continuously running watcher has different tradeoffs from one-shot task execution because task reruns happen repeatedly and may be triggered by the files those tasks produce.

Sources: apps/docs/content/docs/reference/watch.mdx

turbo watch your-tasks --experimental-write-cache

The task-output limitation is the most important operational warning on the page. If a watched task writes files that are checked into source control, watch mode can enter an infinite loop: a file changes, a task runs, the task writes another watched file, and that write triggers the task again. The docs note that watch mode uses file hashes to reduce this risk, but the protection is not foolproof. The recommended mitigation is to remove task outputs from version control so generated artifacts do not look like fresh source edits.

Sources: apps/docs/content/docs/reference/watch.mdx

This limitation also affects how teams should design outputs and repository hygiene. A generated distribution directory, compiled declaration file, or formatted artifact may be useful, but if it is both written by a task and tracked as source, it can create noisy watch behavior. Prefer clear output directories, accurate task output configuration, and an ignore strategy that keeps generated files out of the change stream developers edit directly. Watch mode works best when source files and task products are separated, because then file system events more accurately represent developer intent.

Sources: apps/docs/content/docs/reference/watch.mdx

Configuration Touchpoints and Reference Notes

The watch command depends on the same configuration concepts used elsewhere in Turborepo. The relevant fields named in the docs are task dependencies, inputs, persistent, interruptible, and the future flag for task-input watching. Task dependencies determine rerun order. Inputs determine task-level relevance when the future flag is enabled. Persistent identifies tasks that do not exit and therefore cannot participate as graph prerequisites. Interruptible allows a long-running task to be restarted when watch mode detects relevant changes. These configuration choices should be reviewed together, not as isolated toggles.

Sources: apps/docs/content/docs/reference/watch.mdx

A compact reference for day-to-day use is: run the command with task names when you want file changes to trigger graph-aware reruns; run it without task names to inspect available tasks; keep framework development servers persistent when they already watch dependencies correctly; mark non-aware long-running tools interruptible when they need restarts; use task-input watching when package-level reruns are too broad; and be cautious with experimental cache writes. If watch mode feels too noisy, first inspect changed files, task outputs, and input globs before assuming the scheduler is wrong.

Sources: apps/docs/content/docs/reference/watch.mdx

Next Steps

After learning watch mode, read the run command reference because watch mode intentionally mirrors important execution behavior from normal task runs. Then review configuration for dependencies, inputs, persistent tasks, interruptible tasks, and future flags, because those settings control the practical behavior described here. For development workflows, connect this page to the guidance on developing applications so each package uses the right watcher: a framework’s native watcher when it is dependency-aware, or Turborepo watch when repository-level graph coordination is the missing piece.

Sources: apps/docs/content/docs/reference/watch.mdx