Docs: Add sections for package manager check disabling. (#8739)

### Description Documenting #8738 to allow for skipping the `packageManager` field in `package.json`. ### Testing Instructions 👀
vercel · Jul 22, 2024 · 5d31f76 · 5d31f76
1 parent 67c9781
commit 5d31f76
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 24 deletions.
diff --git a/docs/repo-docs/reference/configuration.mdx b/docs/repo-docs/reference/configuration.mdx
@@ -81,7 +81,7 @@ Additionally, Turborepo has a built-in set of global passthrough variables for c
  include them in [`env`](#env) or [`globalEnv`](#globalenv).
 </Callout>
 
-### ui
+### `ui`
 
 Default: `"stream"`
 
@@ -95,6 +95,28 @@ Select a terminal UI for the repository.
 }
 ```
 
+### `dangerouslyDisablePackageManagerCheck`
+
+Default: `false`
+
+Turborepo uses your repository's lockfile to determine caching behavior, [Package Graphs](https://turbo.build/repo/docs/core-concepts/internal-packages), and more. Because of this, we use [the `packageManager` field](https://nodejs.org/api/packages.html#packagemanager) to help you stabilize your Turborepo.
+
+To help with incremental migration or in situations where you can't use the `packageManager` field, you may use `--dangerously-disable-package-manager-check` to opt out of this check and assume the risks of unstable lockfiles producing unpredictable behavior. When disabled, Turborepo will attempt a best-effort discovery of the intended package manager meant for the repository.
+
+```jsonc title="./turbo.json"
+{
+ "dangerouslyDisablePackageManagerCheck": true
+}
+```
+
+<Callout type="info">
+ You may also opt out of this check via
+ [`flag`](/repo/docs/reference/run#dangerously-disable-package-manager-check)
+ or the
+ [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](https://turbo.build/repo/docs/reference/system-environment-variables)
+ environment variable.
+</Callout>
+
 ## Defining tasks
 
 ### `tasks`

diff --git a/docs/repo-docs/reference/run.mdx b/docs/repo-docs/reference/run.mdx
@@ -82,6 +82,20 @@ Set the working directory of the command.
 turbo run build --cwd=./somewhere/else/in/your/repo
 ```
 
+### `--dangerously-disable-package-manager-check`
+
+Turborepo uses your repository's lockfile to determine caching behavior, [Package Graphs](https://turbo.build/repo/docs/core-concepts/internal-packages), and more. Because of this, we use [the `packageManager` field](https://nodejs.org/api/packages.html#packagemanager) to help you stabilize your Turborepo.
+
+To help with incremental migration or in situations where you cannot use the `packageManager` field, you may use `--dangerously-disable-package-manager-check` to opt out of this check and assume the risks of unstable lockfiles producing unpredictable behavior. When disabled, Turborepo will attempt a best-effort discovery of the intended package manager meant for the repository.
+
+<Callout type="info">
+ You may also opt out of this check using [configuration in
+ `turbo.json`](/repo/docs/reference/configuration#dangerouslydisablepacakgemanagercheck)
+ or the
+ [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](/repo/docs/reference/system-environment-variables)
+ environment variable for broader coverage.
+</Callout>
+
 ### `--dry / --dry-run`
 
 Instead of executing tasks, display details about the packages and tasks that would be run.

diff --git a/docs/repo-docs/reference/system-environment-variables.mdx b/docs/repo-docs/reference/system-environment-variables.mdx
@@ -9,29 +9,30 @@ By setting certain environment variables, you can change Turborepo's behavior. T
 
 System environment variables are always overridden by flag values provided directly to your `turbo` commands.
 
-| Variable | Description |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TURBO_API` | Set the base URL for [Remote Cache](/repo/docs/core-concepts/remote-caching). |
-| `TURBO_BINARY_PATH` | Manually set the path to the `turbo` binary. By default, `turbo` will automatically discover the binary so you should only use this in rare circumstances. |
-| `TURBO_CACHE_DIR` | Sets the cache directory, similar to using [`--cache-dir`](/repo/docs/reference/run#--cache-dir-path) flag |
-| `TURBO_CI_VENDOR_ENV_KEY` | Set a prefix for environment variables that you want **excluded** from [Framework Inference](/repo/docs/crafting-your-repository/using-environment-variables#framework-inference). |
-| `TURBO_DOWNLOAD_LOCAL_ENABLED` | Enables global `turbo` to install the correct local version if one is not found. |
-| `TURBO_FORCE` | Always force all tasks to run in full, opting out of all caching. |
-| `TURBO_GLOBAL_WARNING_DISABLED` | Disable warning when global `turbo` cannot find a local version to use. |
-| `TURBO_LOG_ORDER` | Set the [log order](/repo/docs/reference/run#--log-order-option). Allowed values are `grouped` and `default`. |
-| `TURBO_LOGIN` | Set the URL used to log in to [Remote Cache](/repo/docs/core-concepts/remote-caching). |
-| `TURBO_NO_UPDATE_NOTIFIER` | Remove the update notifier that appears when a new version of `turbo` is available. You can also use `NO_UPDATE_NOTIFIER` per ecosystem convention. |
-| `TURBO_PREFLIGHT` | Enables sending a preflight request before every cache artifact and analytics request. The follow-up upload and download will follow redirects. Only applicable when [Remote Caching](/repo/docs/core-concepts/remote-caching) is configured. |
-| `TURBO_REMOTE_CACHE_READ_ONLY` | Prevent writing to the [Remote Cache](/repo/docs/core-concepts/remote-caching) - but still allow reading. |
-| `TURBO_REMOTE_CACHE_SIGNATURE_KEY` | Sign artifacts with a secret key. For more information, visit [the Artifact Integrity section](/repo/docs/core-concepts/remote-caching#artifact-integrity-and-authenticity-verification). |
-| `TURBO_REMOTE_CACHE_TIMEOUT` | Set a timeout in seconds for `turbo` to get artifacts from [Remote Cache](/repo/docs/core-concepts/remote-caching). |
-| `TURBO_REMOTE_ONLY` | Always ignore the local filesystem cache for all tasks. |
-| `TURBO_RUN_SUMMARY` | Generate a [Run Summary](/repo/docs/reference/run#--summarize) when you run tasks. |
-| `TURBO_TEAM` | The account name associated with your repository. When using [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching#vercel-remote-cache), this is your team's slug. |
-| `TURBO_TEAMID` | The account identifier associated with your repository. When using [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching#vercel-remote-cache), this is your team's ID. |
-| `TURBO_TELEMETRY_MESSAGE_DISABLED` | Disable the message notifying you that [Telemetry](/repo/docs/telemetry) is enabled. |
-| `TURBO_TOKEN` | The Bearer token for authentication to access [Remote Cache](/repo/docs/core-concepts/remote-caching). |
-| `TURBO_UI` | Enables TUI when passed true or 1, disables when passed false or 0. |
+| Variable | Description |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TURBO_API` | Set the base URL for [Remote Cache](/repo/docs/core-concepts/remote-caching). |
+| `TURBO_BINARY_PATH` | Manually set the path to the `turbo` binary. By default, `turbo` will automatically discover the binary so you should only use this in rare circumstances. |
+| `TURBO_CACHE_DIR` | Sets the cache directory, similar to using [`--cache-dir`](/repo/docs/reference/run#--cache-dir-path) flag |
+| `TURBO_CI_VENDOR_ENV_KEY` | Set a prefix for environment variables that you want **excluded** from [Framework Inference](/repo/docs/crafting-your-repository/using-environment-variables#framework-inference). |
+| `TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK` | Disable checking the `packageManager` field in `package.json`. You may run into [errors and unexpected caching behavior](/repo/docs/reference/configuration#dangerouslydisablepacakgemanagercheck) when disabling this check. Use `true` or `1` to disable. |
+| `TURBO_DOWNLOAD_LOCAL_ENABLED` | Enables global `turbo` to install the correct local version if one is not found. |
+| `TURBO_FORCE` | Always force all tasks to run in full, opting out of all caching. |
+| `TURBO_GLOBAL_WARNING_DISABLED` | Disable warning when global `turbo` cannot find a local version to use. |
+| `TURBO_LOG_ORDER` | Set the [log order](/repo/docs/reference/run#--log-order-option). Allowed values are `grouped` and `default`. |
+| `TURBO_LOGIN` | Set the URL used to log in to [Remote Cache](/repo/docs/core-concepts/remote-caching). |
+| `TURBO_NO_UPDATE_NOTIFIER` | Remove the update notifier that appears when a new version of `turbo` is available. You can also use `NO_UPDATE_NOTIFIER` per ecosystem convention. |
+| `TURBO_PREFLIGHT` | Enables sending a preflight request before every cache artifact and analytics request. The follow-up upload and download will follow redirects. Only applicable when [Remote Caching](/repo/docs/core-concepts/remote-caching) is configured. |
+| `TURBO_REMOTE_CACHE_READ_ONLY` | Prevent writing to the [Remote Cache](/repo/docs/core-concepts/remote-caching) - but still allow reading. |
+| `TURBO_REMOTE_CACHE_SIGNATURE_KEY` | Sign artifacts with a secret key. For more information, visit [the Artifact Integrity section](/repo/docs/core-concepts/remote-caching#artifact-integrity-and-authenticity-verification). |
+| `TURBO_REMOTE_CACHE_TIMEOUT` | Set a timeout in seconds for `turbo` to get artifacts from [Remote Cache](/repo/docs/core-concepts/remote-caching). |
+| `TURBO_REMOTE_ONLY` | Always ignore the local filesystem cache for all tasks. |
+| `TURBO_RUN_SUMMARY` | Generate a [Run Summary](/repo/docs/reference/run#--summarize) when you run tasks. |
+| `TURBO_TEAM` | The account name associated with your repository. When using [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching#vercel-remote-cache), this is your team's slug. |
+| `TURBO_TEAMID` | The account identifier associated with your repository. When using [Vercel Remote Cache](https://vercel.com/docs/monorepos/remote-caching#vercel-remote-cache), this is your team's ID. |
+| `TURBO_TELEMETRY_MESSAGE_DISABLED` | Disable the message notifying you that [Telemetry](/repo/docs/telemetry) is enabled. |
+| `TURBO_TOKEN` | The Bearer token for authentication to access [Remote Cache](/repo/docs/core-concepts/remote-caching). |
+| `TURBO_UI` | Enables TUI when passed true or 1, disables when passed false or 0. |
 
 ## Environment variables in tasks