Deploy tests now use the checkout's built JavaScript packages when
`NEXT_TEST_VERSION` is unset. The harness reuses the isolated-test
packer, includes the tarballs in the deployment source, and installs
them through relative `file:` references.
The previous published-build workflow remains available through
`NEXT_TEST_VERSION`. For example, `NEXT_TEST_VERSION=canary` skips local
packing and tests the published canary. Exact versions and CI preview
tarball URLs remain supported. Existing CI deploy jobs already set
`NEXT_TEST_VERSION`, so their package selection does not change. The
harness skips local package preparation when it reuses an existing
deployment or invokes a custom deploy script, preserving those
workflows.
Staged monorepo peer dependencies use matching local versions so npm
accepts prerelease builds without conflicting direct-package overrides.
Fixture overrides retain their nested rules, including qualified
identity overrides with or without an explicit `.` entry. Configuration
updates preserve linked source files.
Deployments of local JavaScript packages use published SWC binaries
matching the local Next.js version. They do not include locally built
native binaries because those may target a different platform.
**Verification**
```
VERCEL_TURBOPACK_TEST_TEAM=vtest314-next-turbo-e2e-tests \
pnpm test-deploy-turbo test/e2e/app-dir/third-parties/basic.test.ts
```
```
VERCEL_TEST_TEAM=vtest314-next-turbo-e2e-tests \
pnpm test-deploy-webpack test/e2e/app-dir/third-parties/basic.test.ts
```
Both deploy modes passed. Additional temporary checks, removed
afterward, verified that:
- Deployments install the local JavaScript packages and use matching
local versions for monorepo peers.
- Qualified npm overrides preserve a nested `sharp@0.34.5` pin, both
with and without an explicit `.` entry. The check resolved `sharp` from
Next's own dependency context.
- Archive preparation leaves checkout manifests and tarballs unchanged.
Repacked archives preserve other package files, permissions, links, and
external peer declarations.
Fixed two typos in `contributing/core/testing.md`:
- `sett` → `setting` (`Consider also setting NEXT_E2E_TEST_TIMEOUT=0`)
- `again` → `against` (`run a test against both Turbopack and Webpack`)
### What?
Adds a `--deployable-tar` option to `pack-next` that writes generated
tarballs into the target project and patches package references to use
relative `file:` paths.
### Why?
Projects that need to deploy with locally packed Next.js packages should
be able to include those tarballs inside the project directory instead
of referencing tarballs from the Next.js checkout.
### How?
Resolves the target project package.json location, writes tarballs to a
sibling `tarballs/` directory, and maps package override paths to
project-relative references when patching package.json. Existing `--tar`
behavior continues to write to the repository tarballs directory.
### Verification
- `git diff --check`
- `git diff --cached --check`
- `pnpm prettier --with-node-modules --ignore-path .prettierignore
--write scripts/pack-next.ts scripts/pack-utils/patch-package-json.ts
contributing/core/testing.md contributing/core/developing.md`
- `npx eslint --config eslint.config.mjs --fix scripts/pack-next.ts
scripts/pack-utils/patch-package-json.ts contributing/core/testing.md
contributing/core/developing.md` (Markdown files were ignored because no
matching ESLint config was supplied)
- `pnpm pack-next --project ../sandbox/nextjs-duplicated-html-repro/
--deployable-tar`
<!-- NEXT_JS_LLM_PR -->
When digging into failing deployment tests, I often will re-run the test
itself without wanting to change anything about Next.js or the test
application, especially when I suspect a logic bug in the test itself or
need to figure out what's causing a flake.
This adds an environment variable that can be used to skip the
build/deploy step and will use an existing deployment URL to run the
tests against.
I suggest reviewing this [without
whitespace](https://github.com/vercel/next.js/pull/88829/changes?w=1).
This makes certain aggregations trivial since we are are guaranteed to only traverse relevant edges.
Use it to fix a bug in the async module identification logic. Previously we would aggregate async cycles after propagating 'asyncness' through the DFS post order traversal, but this could cause us to fail to propagate async to all reverse dependencies depending on which part of a cycle a node would happen to visit first.
By traversing starting from the async modules we just need to mark everything we find and not worry about cycles at all since the underlying DFS mechanism will ensure we don't loop. In addition to only requiring a single pass, this is guaranteed to visit fewer nodes in that single pass.
One caveat is that reverse traversals only work within a single `SingleModuleGraph` so a debug assert was added to prevent misuse
Closes#85988Closes#86391
Closes PACK-5806
Written with @bgw.
- Transitions to using `tsx` for script execution
- Replaces `patch-package` with TypeScript implementation
- Implements argument parsing and help message with `yargs`
- Uses `execa` for some command execution
Test Plan: Run `pnpm pack-next`, `pnpm swc-build-wasm`, `pnpm unpack-next`, and `pnpm sweep` without errors.
I commonly add a `debug` script that allows me to attach a debugger when running Next.js in the isolated test dirs.
Now we always add it and make it work just like `debug` from the monorepo. So after the test you can `cd` into the created test directory and run `pnpm debug dev`. `debug` is just an alias for `next` with some additional configurations:
- tracing deprecations
- no telemetry
- no canary checks
- debugger attachable
- source maps
`debug` also ensures the SWC version that was used during the test is used. Previously it used the cached version which isn't necessarily the one built in this specific worktree.
## What is `pack-next`?
This is a script we use for developing turbopack. It builds tarballs for
all the next.js packages, including `next-swc`, and then provides
instructions about how to modify a project's `package.json` to install
from that tarball.
## What does this PR do?
If you provide a `--project ~/path/to/directory` argument to `pnpm
pack-next`, we'll auto-update the `package.json` there for you, instead
of telling you how to do it manually!
This also understands the React 19 RC peer dependencies, which is
something that was missing from the generated instructions.
## Supported Package Managers
I've tested this with `npm` and `pnpm`.
- `bun` fails with `ENOTDIR` for unknown reasons (maybe it's trying to
handle the local tarball as a directory instead of a tarball?).
- `yarn` fails due to an upstream issue:
https://github.com/yarnpkg/yarn/issues/6339
This does generate the entries for yarn's `resolutions` feature,
assuming the upstream issue is eventually fixed.
## Why Rust and `cargo xtask`?
https://github.com/matklad/cargo-xtask
I'd love for these Turbopack-centric scripts to be written in Rust with
xtask, since they're mostly touched by the turbopack team.
However, it's also hard to justify putting too much effort into these
development scripts, so I don't want to rewrite the whole thing right
now.
I figured I'd write the new functionality in Rust and call it from the
old JS script.
## Test Plan
Perform a fresh checkout of shadcn/ui, and then:
```
pnpm pack-next --project ~/shadcn-ui/apps/www/
```
```
Found workspace! Patching "/home/bgw.linux/shadcn-ui/package.json" with overrides.
Successfully patched "/home/bgw.linux/shadcn-ui/package.json" to use local tarball files!
Run `pnpm i` or `npm i` to install the overrides
```
Check the resulting changes to `~/shadcn-ui`:
```diff
diff --git a/package.json b/package.json
index be47ad7..262c13b 100644
--- a/package.json
+++ b/package.json
@@ -63,12 +63,31 @@
"tsx": "^4.1.4",
"turbo": "^1.9.9",
"vite-tsconfig-paths": "^4.2.0",
- "vitest": "^0.31.1"
+ "vitest": "^0.31.1",
+ "@next/swc": "file:/home/bgw.linux/next.js/tarballs/next-swc.tar"
},
"devDependencies": {
"@types/node": "^20.11.27",
"@types/react": "^18.2.65",
"@types/react-dom": "^18.2.22",
"typescript": "^5.5.3"
+ },
+ "overrides": {
+ "next": "file:/home/bgw.linux/next.js/tarballs/next.tar",
+ "@next/mdx": "file:/home/bgw.linux/next.js/tarballs/next-mdx.tar",
+ "@next/env": "file:/home/bgw.linux/next.js/tarballs/next-env.tar",
+ "@next/bundle-analyzer": "file:/home/bgw.linux/next.js/tarballs/next-bundle-analyzer.tar",
+ "@next/swc": "file:/home/bgw.linux/next.js/tarballs/next-swc.tar",
+ "react": "19.0.0-rc-7771d3a7-20240827",
+ "react-dom": "19.0.0-rc-7771d3a7-20240827"
+ },
+ "resolutions": {
+ "next": "file:/home/bgw.linux/next.js/tarballs/next.tar",
+ "@next/mdx": "file:/home/bgw.linux/next.js/tarballs/next-mdx.tar",
+ "@next/env": "file:/home/bgw.linux/next.js/tarballs/next-env.tar",
+ "@next/bundle-analyzer": "file:/home/bgw.linux/next.js/tarballs/next-bundle-analyzer.tar",
+ "@next/swc": "file:/home/bgw.linux/next.js/tarballs/next-swc.tar",
+ "react": "19.0.0-rc-7771d3a7-20240827",
+ "react-dom": "19.0.0-rc-7771d3a7-20240827"
}
}
```
## What?
Adds instructions for how to run tests with Turbopack and how to run
tests while recording using Replay.io.
I've also updated the instructions to mention `test-dev` and
`test-start` which are the commands we generally use.
<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:
## For Contributors
### Improving Documentation
- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide
### Adding or Updating Examples
- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md
### Fixing a bug
- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
### Adding a feature
- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md
## For Maintainers
- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change
### What?
### Why?
### How?
Closes NEXT-
Fixes #
-->
Closes NEXT-2031
close https://github.com/vercel/next.js/issues/41378
add tips for building first before running tests for contribute Nextjs
## Documentation / Examples
- [x] Make sure the linting passes by running `pnpm lint`
Continues #39778Closes#40499
## Bug
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`
## Feature
- [ ] Implements an existing feature request or RFC. Make sure the
feature request has been accepted for implementation before opening a
PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`
## Documentation / Examples
- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The examples guidelines are followed from [our contributing
doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
Co-authored-by: JJ Kasper <jj@jjsweb.site>
Hendrik Liebau
