Skip to content

docs: declare packageManager in the migration how-to #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arbrandes merged 1 commit into from
Aug 30, 2026
Merged

docs: declare packageManager in the migration how-to #313

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/how_tos/migrate-frontend-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1153,6 +1153,14 @@ Install ``turbo`` and ``nodemon`` as dev dependencies:
npm install --save-dev turbo nodemon
```

Declare the package manager in ``package.json``, using the exact npm version you develop against:

```json
"packageManager": "npm@11.12.1",
```

Turbo 2.10.1 and later rely on this field to detect the workspace. Without it turbo falls back to single-package mode and rejects the ``//#dev:site`` root task, so ``make build-packages`` fails with ``package_task_in_single_package_mode``. The version must be exact, since Corepack rejects ranges.

Then add the following scripts to ``package.json``:

```json
Expand All @@ -1166,7 +1174,7 @@ Then add the following scripts to ``package.json``:
And add the corresponding Makefile targets:

```makefile
TURBO = TURBO_TELEMETRY_DISABLED=1 turbo --dangerously-disable-package-manager-check
TURBO = TURBO_TELEMETRY_DISABLED=1 turbo

# turbo.site.json is the standalone turbo config for this package. It is
# renamed to avoid conflicts with turbo v2's workspace validation, which
Expand Down Expand Up @@ -1200,7 +1208,7 @@ dev-site: bin-link
- ``dev:site`` is an alias for ``npm run dev`` that also bin-links the frontend-base bin files; turbo uses it as a root-only task (``//#dev:site``).
- ``dev:packages`` depends on ``build-packages`` so the CLI is available before starting the watch, then concurrently watches workspace packages for changes and starts the dev server.

The Makefile targets copy ``turbo.site.json`` to ``turbo.json`` before invoking turbo, then remove the copy afterward. This ensures turbo finds its expected config when running standalone, without leaving a ``turbo.json`` that would conflict in a workspace context. The ``--dangerously-disable-package-manager-check`` flag and ``TURBO_TELEMETRY_DISABLED=1`` are also set here, keeping turbo invocation details in one place.
The Makefile targets copy ``turbo.site.json`` to ``turbo.json`` before invoking turbo, then remove the copy afterward. This ensures turbo finds its expected config when running standalone, without leaving a ``turbo.json`` that would conflict in a workspace context. ``TURBO_TELEMETRY_DISABLED=1`` is also set here, keeping turbo invocation details in one place.

Using workspaces
-----------------
Expand Down