babel-plugin-validate-jsx-nesting

The Problem

Certain HTML elements have nesting restrictions. For example, placing an <hr> inside a <p> is invalid. When browsers encounter this, they silently modify the DOM to fix it.

If you write this JSX:

<p>
  Hello
  <hr />
  World
</p>

The browser creates this DOM:

<p>Hello</p>
<hr />
<p>World</p>

The paragraph gets split, and the <hr> ends up outside of it. This mismatch between your JSX and the actual DOM causes hydration errors in React and other frameworks that assume the DOM matches what was rendered.

The Solution

This Babel plugin catches invalid nesting at compile time. Instead of discovering the bug in production through a cryptic hydration error, you get a clear message during development:

Error: Invalid HTML nesting: <hr> cannot be child of <p>

  1 | <p>
  2 |   Hello
> 3 |   <hr />
    |   ^^^^^^
  4 |   World
  5 | </p>

Setup

Install babel-plugin-validate-jsx-nesting and add it to your Babel config:

{
  "plugins": ["validate-jsx-nesting"]
}

To log warnings instead of failing the build, use the warnOnly option:

{
  "plugins": [["validate-jsx-nesting", { "warnOnly": true }]]
}

Related