Next.js docs broken links #89115

ismaelrumzan · 2026-01-27T16:36:56Z

For Maintainers

What?

Created BROKEN_LINKS_ANALYSIS.md to document an investigation into reported broken links on nextjs.org. This file details:

A list of 5 broken /docs links reported on nextjs.org.
Their correct target paths in the current vercel/next.js documentation.
The corresponding redirect rules to be implemented in vercel/front.
An investigation into a 6th reported broken link (/docs/app/api-reference/functions/not-found), concluding the source file exists and the issue is likely deployment-related in vercel/front.

Why?

To address and resolve reported broken links on nextjs.org by providing a clear action plan for the vercel/front repository. The investigation confirmed that the issues stem from external references (e.g., from /learn or /blog pages on nextjs.org) pointing to old or renamed documentation paths, rather than broken links within the vercel/next.js docs source itself.

How?

Performed a comprehensive search and validation of reported broken links within the vercel/next.js /docs folder.
Identified that the broken links are external references pointing to old or renamed documentation paths.
Mapped the old paths to their current, correct counterparts in the vercel/next.js documentation.
Documented the findings and proposed redirect rules in BROKEN_LINKS_ANALYSIS.md.

Closes NEXT-
Fixes #

Slack Thread

- Analyzed 28 broken links reported on nextjs.org - Identified correct redirect targets for old documentation paths - Documented that source files exist in vercel/next.js - Redirects need to be implemented in vercel/front repo Reference: Slack #feedback-docs 2026-01-27

cursor · 2026-01-27T16:36:58Z

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

nextjs-bot · 2026-01-27T16:42:33Z

Failing test suites

Commit: e14cf15 | About building and testing Next.js

pnpm test-dev test/e2e/url-deployment-id/url-deployment-id.test.ts (job)

Expand output

● Test suite failed to run

Jest encountered an unexpected token

Jest failed to parse a file. This happens e.g. when your code or its dependencies use non-standard JavaScript syntax, or when Jest is not configured to support such syntax.

Out of the box Jest supports Babel, which will be used to transform your files into valid JS based on your Babel configuration.

By default "node_modules" folder is ignored by transformers.

Here's what you can do:
 • If you are trying to use ECMAScript Modules, see https://jestjs.io/docs/ecmascript-modules for how to enable it.
 • If you are trying to use TypeScript, see https://jestjs.io/docs/getting-started#using-typescript
 • To have some of your "node_modules" files transformed, you can specify a custom "transformIgnorePatterns" in your config.
 • If you need a custom transformation specify a "transform" option in your config.
 • If you simply want to mock your non-JS modules (e.g. binary assets) you can stub them out with the "moduleNameMapper" config option.

You'll find more details and examples of these config options in the docs:
https://jestjs.io/docs/configuration
For information about custom transformations, see:
https://jestjs.io/docs/code-transformation

Details:

/root/actions-runner/_work/next.js/next.js/test/e2e/url-deployment-id/url-deployment-id.test.ts:1
({"Object.<anonymous>":function(module,exports,require,__dirname,__filename,jest){import { nextTestSetup } from 'e2e-utils';
                                                                                  ^^^^^^

SyntaxError: Cannot use import statement outside a module

  at Runtime.createScriptFromCode (../node_modules/.pnpm/jest-runtime@29.7.0/node_modules/jest-runtime/build/index.js:1505:14)

nextjs-bot · 2026-01-27T16:54:45Z

Stats from current PR

✅ No significant changes detected

📊 All Metrics

📖 Metrics Glossary

Dev Server Metrics:

Listen = TCP port starts accepting connections
First Request = HTTP server returns successful response
Cold = Fresh build (no cache)
Warm = With cached build artifacts

Build Metrics:

Fresh = Clean build (no .next directory)
Cached = With existing .next directory

Change Thresholds:

Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
Size: Changes < 1KB AND < 1% are insignificant
All other changes are flagged to catch regressions

⚡ Dev Server

Metric	Canary	PR	Change	Trend
Cold (Listen)	456ms	455ms	✓	█▁▁▁▁
Cold (Ready in log)	437ms	438ms	✓	▃▁▇█▁
Cold (First Request)	1.158s	1.125s	✓	▂▂█▇▁
Warm (Listen)	457ms	456ms	✓	█▁▁▁▁
Warm (Ready in log)	442ms	442ms	✓	▆▃▁▂▁
Warm (First Request)	336ms	338ms	✓	▄▄▁▂▅

📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric	Canary	PR	Change	Trend
Cold (Listen)	457ms	456ms	✓	█▅▅▅▅
Cold (Ready in log)	441ms	440ms	✓	▂█▃▄▆
Cold (First Request)	1.779s	1.775s	✓	▂█▃▅▃
Warm (Listen)	457ms	456ms	✓	▃▆▃▃▃
Warm (Ready in log)	443ms	442ms	✓	▂█▅▆▃
Warm (First Request)	1.787s	1.792s	✓	▂█▅▆▁

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	4.199s	4.257s	✓	▇▅▁▂▂
Cached Build	4.244s	4.204s	✓	▅▄▁▁▂

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
Fresh Build	14.051s	14.008s	✓	▁█▄▇▁
Cached Build	14.139s	14.122s	✓	▁▄▂▃▁
node_modules Size	462 MB	462 MB	✓	█████

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **432 kB** → **432 kB** ✅ -24 B

81 files with content-based hashes (individual files not comparable between builds)

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	771 B	764 B	✓
Total	771 B	764 B	✅ -7 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	449 B	452 B	✓
Total	449 B	452 B	⚠️ +3 B

📦 Webpack

Client

Main Bundles

	Canary	PR	Change
5528-HASH.js gzip	5.47 kB	N/A	-
6280-HASH.js gzip	52.6 kB	N/A	-
6335.HASH.js gzip	169 B	N/A	-
912-HASH.js gzip	4.53 kB	N/A	-
e8aec2e4-HASH.js gzip	62.3 kB	N/A	-
framework-HASH.js gzip	59.7 kB	59.7 kB	✓
main-app-HASH.js gzip	256 B	254 B	✓
main-HASH.js gzip	39 kB	39 kB	✓
webpack-HASH.js gzip	1.68 kB	1.68 kB	✓
262-HASH.js gzip	N/A	4.52 kB	-
2889.HASH.js gzip	N/A	169 B	-
5602-HASH.js gzip	N/A	5.48 kB	-
6948ada0-HASH.js gzip	N/A	62.3 kB	-
9544-HASH.js gzip	N/A	53.1 kB	-
Total	226 kB	226 kB	⚠️ +487 B

Polyfills

	Canary	PR	Change
polyfills-HASH.js gzip	39.4 kB	39.4 kB	✓
Total	39.4 kB	39.4 kB	✓

Pages

	Canary	PR	Change
_app-HASH.js gzip	194 B	194 B	✓
_error-HASH.js gzip	183 B	180 B	🟢 3 B (-2%)
css-HASH.js gzip	331 B	330 B	✓
dynamic-HASH.js gzip	1.81 kB	1.81 kB	✓
edge-ssr-HASH.js gzip	256 B	256 B	✓
head-HASH.js gzip	351 B	352 B	✓
hooks-HASH.js gzip	384 B	383 B	✓
image-HASH.js gzip	580 B	581 B	✓
index-HASH.js gzip	260 B	260 B	✓
link-HASH.js gzip	2.49 kB	2.49 kB	✓
routerDirect..HASH.js gzip	320 B	319 B	✓
script-HASH.js gzip	386 B	386 B	✓
withRouter-HASH.js gzip	315 B	315 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Total	7.97 kB	7.97 kB	✅ -1 B

Server

Edge SSR

	Canary	PR	Change
edge-ssr.js gzip	126 kB	126 kB	✓
page.js gzip	246 kB	247 kB	✓
Total	373 kB	373 kB	⚠️ +245 B

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	617 B	616 B	✓
middleware-r..fest.js gzip	156 B	155 B	✓
middleware.js gzip	33.1 kB	33 kB	✓
edge-runtime..pack.js gzip	842 B	842 B	✓
Total	34.7 kB	34.6 kB	✅ -101 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	732 B	736 B	✓
Total	732 B	736 B	⚠️ +4 B

Build Cache

	Canary	PR	Change
0.pack gzip	3.71 MB	3.72 MB	🔴 +11.6 kB (+0%)
index.pack gzip	102 kB	101 kB	✓
index.pack.old gzip	101 kB	101 kB	✓
Total	3.92 MB	3.93 MB	⚠️ +10.4 kB

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	308 kB	308 kB	✓
app-page-exp..prod.js gzip	164 kB	164 kB	✓
app-page-tur...dev.js gzip	308 kB	308 kB	✓
app-page-tur..prod.js gzip	164 kB	164 kB	✓
app-page-tur...dev.js gzip	305 kB	305 kB	✓
app-page-tur..prod.js gzip	162 kB	162 kB	✓
app-page.run...dev.js gzip	305 kB	305 kB	✓
app-page.run..prod.js gzip	162 kB	162 kB	✓
app-route-ex...dev.js gzip	70.2 kB	70.2 kB	✓
app-route-ex..prod.js gzip	48.8 kB	48.8 kB	✓
app-route-tu...dev.js gzip	70.2 kB	70.2 kB	✓
app-route-tu..prod.js gzip	48.8 kB	48.8 kB	✓
app-route-tu...dev.js gzip	69.8 kB	69.8 kB	✓
app-route-tu..prod.js gzip	48.6 kB	48.6 kB	✓
app-route.ru...dev.js gzip	69.7 kB	69.7 kB	✓
app-route.ru..prod.js gzip	48.6 kB	48.6 kB	✓
dist_client_...dev.js gzip	324 B	324 B	✓
dist_client_...dev.js gzip	326 B	326 B	✓
dist_client_...dev.js gzip	318 B	318 B	✓
dist_client_...dev.js gzip	317 B	317 B	✓
pages-api-tu...dev.js gzip	43.1 kB	43.1 kB	✓
pages-api-tu..prod.js gzip	32.8 kB	32.8 kB	✓
pages-api.ru...dev.js gzip	43.1 kB	43.1 kB	✓
pages-api.ru..prod.js gzip	32.8 kB	32.8 kB	✓
pages-turbo....dev.js gzip	52.4 kB	52.4 kB	✓
pages-turbo...prod.js gzip	39.3 kB	39.3 kB	✓
pages.runtim...dev.js gzip	52.3 kB	52.3 kB	✓
pages.runtim..prod.js gzip	39.3 kB	39.3 kB	✓
server.runti..prod.js gzip	62.5 kB	62.5 kB	✓
Total	2.75 MB	2.75 MB	⚠️ +1 B

nextjs-bot added the created-by: Next.js DevEx team PRs by the DX team. label Jan 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Next.js docs broken links #89115

Next.js docs broken links #89115

ismaelrumzan commented Jan 27, 2026

cursor bot commented Jan 27, 2026

nextjs-bot commented Jan 27, 2026

nextjs-bot commented Jan 27, 2026

⚡ Dev Server

📦 Dev Server (Webpack)

⚡ Production Builds

📦 Production Builds (Webpack)

Bundle Sizes

⚡ Turbopack

📦 Webpack

🔄 Shared (bundler-independent)

Labels

4 participants

Next.js docs broken links #89115

Are you sure you want to change the base?

Next.js docs broken links #89115

Conversation

ismaelrumzan commented Jan 27, 2026

For Maintainers

What?

Why?

How?

cursor bot commented Jan 27, 2026

nextjs-bot commented Jan 27, 2026

Failing test suites

nextjs-bot commented Jan 27, 2026

Stats from current PR

✅ No significant changes detected

⚡ Dev Server

📦 Dev Server (Webpack)

⚡ Production Builds

📦 Production Builds (Webpack)

Bundle Sizes

⚡ Turbopack

📦 Webpack

🔄 Shared (bundler-independent)

Labels

4 participants