nextjs - 💡(How to fix) Fix Docs and runtime disagree on Partytown package name for `nextScriptWorkers` [1 comments, 2 participants]

Link to the code that reproduces this issue

https://github.com/vercel/next.js/blob/8cbab6e69440d923e87a01a3c6fde4ef4dcc91c4/docs/01-app/02-guides/scripts.mdx#offloading-scripts-to-a-web-worker-experimental

To Reproduce

1. Enable experimental.nextScriptWorkers: true in next.config.js.
2. Add a <Script strategy="worker" src="..." /> to any page.
3. Install the package named in the docs: yarn add --dev @qwik.dev/partytown.
4. Run next dev.

Current vs. Expected behavior

Expected: dev server starts and Partytown lib files are copied to public/_next/static/~partytown/.

Actual: build aborts with the "missing required package" error, still asking for @builder.io/partytown.

Installing @builder.io/partytown works, but that package is deprecated on npm.

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.4.0: Thu Mar 19 19:33:25 PDT 2026; root:xnu-12377.101.15~1/RELEASE_ARM64_T6041
  Available memory (MB): 65536
  Available CPU cores: 16
Binaries:
  Node: 24.14.1
  npm: 11.11.0
  Yarn: 4.13.0
  pnpm: N/A
Relevant Packages:
  next: 16.2.3
  eslint-config-next: N/A
  react: 19.1.5
  react-dom: 19.1.5
  typescript: 6.0.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Script (next/script)

Which stage(s) are affected? (Select all that apply)

next dev (local)

Additional context

Which versions are affected

I reproduced this on the latest stable release ([email protected]), and the check in verify-partytown-setup.ts on canary still hardcodes @builder.io/partytown, so the issue persists there as well.

• Next.js: 16.2.3 (stable) — reproduced
• Next.js: canary — still broken per source (see permalink below)

What the docs say

https://nextjs.org/docs/app/guides/scripts#offloading-scripts-to-a-web-worker-experimental

Please install Partytown by running npm install @qwik.dev/partytown

What Next.js actually requires

https://github.com/vercel/next.js/blob/8cbab6e69440d923e87a01a3c6fde4ef4dcc91c4/packages/next/src/lib/verify-partytown-setup.ts#L58

const partytownDeps: NecessaryDependencies = hasNecessaryDependencies(dir, [
  {
    file: "@builder.io/partytown",
    pkg: "@builder.io/partytown",
    exportsRestrict: false,
  },
]);

if (partytownDeps.missing?.length > 0) {
  await missingDependencyError(dir);
}

The error message also hardcodes @builder.io/partytown:

It looks like you're trying to use Partytown with next/script but do not have the required package(s) installed.

yarn add --dev @builder.io/partytown

If you are not trying to use Partytown, please disable the experimental "nextScriptWorkers" flag in next.config.js.

Suggested fix

Update verify-partytown-setup.ts to accept either package (prefer @qwik.dev/partytown, fall back to @builder.io/partytown for back-compat), and update the copyLibFiles resolution + the error message accordingly.

A minimal patch:

const partytownDeps = hasNecessaryDependencies(dir, [
  {
    file: "@qwik.dev/partytown",
    pkg: "@qwik.dev/partytown",
    exportsRestrict: false,
  },
]);

if (partytownDeps.missing?.length > 0) {
  // fallback to the legacy package name
  const legacyDeps = hasNecessaryDependencies(dir, [
    {
      file: "@builder.io/partytown",
      pkg: "@builder.io/partytown",
      exportsRestrict: false,
    },
  ]);
  if (legacyDeps.missing?.length > 0) {
    await missingDependencyError(dir);
  } else {
    await copyPartytownStaticFiles(legacyDeps, targetDir);
    return;
  }
}

await copyPartytownStaticFiles(partytownDeps, targetDir);

The @builder.io/partytown fallback should be removed in the next major Next.js release. The legacy package is already deprecated on npm and will not receive further updates.

I'm happy to open a pull request with this fix, provided I can first get @qwik.dev/partytown running end-to-end against my project so I can verify the change rather than submit it blind.