turbo-ignore

library2.9.6jsnpmunverified

turbo-ignore is a command-line interface (CLI) package designed to optimize CI/CD pipelines, particularly on platforms like Vercel, by selectively skipping builds for projects within a Turborepo monorepo that have not been affected by recent code changes. It operates by analyzing the Turborepo dependency graph and comparing the current commit with a previous reference to determine if a given workspace or its dependencies have changed. If no changes are detected, it exits with a code that signals the CI/CD system (e.g., Vercel's Ignored Build Step) to skip the build, saving time and resources. As of version 2.9.6 (and later canary releases), `turbo-ignore` is *deprecated*. Users are now advised to migrate to `turbo query affected` for more granular and precise task-level change detection directly within Turborepo. While still functional, it no longer receives updates, and its functionality is superseded by built-in `turbo` commands.

devops

npm install turbo-ignore

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TURBO-IGNORE

turbo-ignore

devopsjavascriptv2.9.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This demonstrates how to use `turbo-ignore` in a CI/CD environment, particularly within Vercel's 'Ignored Build Step', to determine if the current project (or a specified workspace) has changes that warrant a build.

npx turbo-ignore <workspace-name> \ --fallback=remotes/origin/${VERCEL_GIT_COMMIT_REF:-main} # Or, for the current directory's workspace, commonly used in Vercel Ignored Build Steps: npx turbo-ignore --fallback=HEAD^1 # Example of how it functions in a Vercel Ignored Build Step: # if `npx turbo-ignore` returns exit code 0, the build is skipped. # if `npx turbo-ignore` returns exit code 1, the build proceeds. # A more robust Vercel Ignored Build Step might look like this: # npx turbo-ignore && exit 0 # echo "Detected changes, proceeding with build." # exit 1

turbo-ignore --version

Debug

Known issues

deprecatedThe `turbo-ignore` package is deprecated and will no longer receive updates. It is recommended to migrate to `turbo query affected` for more precise task-level change detection.

fix

Migrate your CI/CD configurations from `npx turbo-ignore` to use `turbo query affected` commands. Refer to the official Turborepo migration guide for detailed instructions.

affects: >=2.9.0

gotchaWhen using `turbo-ignore` on new branches in CI/CD environments (like Vercel), it may default to building all projects if no previous deployment history is found for that specific branch. This can lead to unnecessary builds.

fix

Always provide a `--fallback` reference to a stable branch (e.g., `--fallback=HEAD^1` or `--fallback=remotes/origin/main`) to ensure comparison against an existing deployment baseline. This helps `turbo-ignore` make accurate decisions even on new branches.

affects: >=1.0.0

gotcha`turbo-ignore` may erroneously mark all applications as 'affected' following any lockfile change, even if the dependency update does not impact specific workspaces. This can result in unnecessary builds across the monorepo.

fix

While `turbo-ignore` is deprecated, this issue is a known limitation. For more granular control over cache invalidation and affected detection, transitioning to `turbo query affected` is the recommended long-term solution.

affects: >=1.0.0

gotchaWhen running `turbo-ignore` outside of a Vercel environment or without appropriate git context, it might fail to correctly identify changes or may require explicit git configuration (e.g., SSH keys for private repos) to compare against remote branches.

fix

Ensure your CI environment has access to the full git history and necessary authentication (e.g., a deploy key) to compare against remote refs. Provide explicit `--fallback` references to ensure correct operation.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'length')

This error often indicates an issue with Turborepo's internal dependency resolution or a mismatch in expected data structures, particularly within Vercel build environments.

fix

Ensure that your `turbo` and `turbo-ignore` versions are compatible. Clear your Vercel build cache. If the issue persists, consider upgrading your Turborepo setup or migrating away from `turbo-ignore` as it's deprecated.

≫ No previous deployments found for "<app-name>" on branch "<branch-name>" ✓ Proceeding with deployment.

This message appears when `turbo-ignore` cannot find a deployment history for the current project on the specific branch being built, typically for new branches or first-time deployments.

fix

To prevent unnecessary builds, use the `--fallback` flag to point to a stable reference (e.g., `HEAD^1` for the previous commit or `remotes/origin/main` for the main branch). This allows `turbo-ignore` to compare against a known state. For example: `npx turbo-ignore --fallback=HEAD^1`.

npm WARN exec The following package was not found and will be installed: turbo-ignore@<version>

`npx` is installing `turbo-ignore` on the fly because it's not present in your `node_modules` or global path. While not an error, it adds overhead to your CI builds.

fix

Add `turbo-ignore` as a `devDependency` to your root `package.json` (`npm install -D turbo-ignore` or `yarn add -D turbo-ignore` or `pnpm add -D turbo-ignore`). This ensures it's installed as part of your `npm ci` or `yarn install` step, making `npx` use the locally installed version.

Upgrade

Version history

2.9.6latest on npm

Audit

Dependencies

turboreporequiredturbo-ignore relies on the turborepo CLI and its configuration to determine affected projects. It dynamically attempts to locate and utilize the correct turborepo version installed in the monorepo.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/vercel/turborepo ↗

packagehttps://www.npmjs.com/package/turbo-ignore ↗

homepagehttps://turborepo.dev ↗