next.js icon indicating copy to clipboard operation
next.js copied to clipboard

Published 20 hours ago • verified publisher icon vercel

Improve error messaging for invalid HTML elements in next/head

Open xabierlameiro opened this issue 5 months ago • 1 comments

For Contributors

Fixing a bug

  • [x] Related issues linked using fixes #number
  • [x] Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
  • [x] Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md

What?

This PR improves the developer experience by providing clear warning messages when invalid HTML elements (<html> or <body>) are used inside next/head.

Why?

Currently, when developers mistakenly put <html> or <body> tags inside next/head, they receive a confusing error message: "next-head-count is missing". This doesn't explain what they did wrong or how to fix it.

How?

• Added validation logic in packages/next/src/shared/lib/head.tsx to detect <html> and <body> elements during development • Show clear warning messages that explain the issue and link to documentation • Added comprehensive tests to verify the warnings are displayed correctly

Changes:

• Modified: packages/next/src/shared/lib/head.tsx - Added validation and warning logic • Added: Test case in test/development/pages-dir/client-navigation/head.test.ts • Added: Test pages for reproducing the issue

Before:

• Confusing "next-head-count is missing" error • No guidance on what caused the issue

After:

• Clear warning: "Do not use tags in next/head. You cannot use to set attributes on or tags. This will result in a 'next-head-count is missing' error." • Includes link to documentation for more information

Fixes #20924

Test Plan

The implementation includes comprehensive tests that verify:

  1. Warning messages are displayed when <html> tags are used in next/head
  2. Warning messages are displayed when <body> tags are used in next/head
  3. Existing functionality remains unaffected

Tests pass with the new warning system in place.

xabierlameiro avatar Jun 14 '25 16:06 xabierlameiro

Allow CI Workflow Run

  • [ ] approve CI run for commit: 51949d06e3ce1a571ab85810ff1ebf340cf0ff7e

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer

ijjk avatar Jun 14 '25 16:06 ijjk