Thread-safe Async React Helmet

Common errors

• TypeError: Cannot destructure property 'Helmet' of 'react-helmet-async' as it is undefined.

  cause Attempting to use a default import for Helmet, but it was removed in v1.0.0.
  fix Change `import Helmet from 'react-helmet-async';` to `import { Helmet } from 'react-helmet-async';`

• Error: Invariant Violation: Hooks can only be called inside the body of a function component.

  cause This error can occur if `react` is duplicated in your `node_modules` or if `react-helmet-async` is incorrectly linked, causing it to use a different React instance than your application. This often happens with monorepos or mismatched peer dependency resolutions.
  fix Check for duplicate `react` installations using `npm ls react` or `yarn why react`. Use a tool like `resolutions` (Yarn) or `overrides` (NPM 8+) to force a single `react` version. Ensure `react` is correctly specified in `peerDependencies` and installed in your project.

• helmetContext.helmet is undefined (during SSR for React 19+)

  cause When running on React 19+, `<title>`, `<meta>`, and `<link>` tags are handled natively by React's head hoisting. The `context` object passed to `HelmetProvider` will therefore not contain these specific tags.
  fix For React 19+, rely on React's native head hoisting for `<title>`, `<meta>`, and `<link>`. If you need to access these tags programmatically on the server, render them directly in your component tree instead of relying solely on `Helmet` and its context extraction.

Warnings

• breaking Starting with version 1.0.0, the package no longer provides a default export. Attempting to use `import Helmet from 'react-helmet-async'` will result in a runtime error.
  Fix: Update all imports to use named imports: `import { Helmet, HelmetProvider } from 'react-helmet-async';`
• breaking For React 19+, `<HelmetProvider>` becomes a transparent passthrough for `<title>`, `<meta>`, and `<link>` elements, as React 19 handles their hoisting natively. The `context` object for SSR will *not* be populated with these elements when running on React 19. `htmlAttributes` and `bodyAttributes` are still applied via direct DOM manipulation.
  Fix: If you rely on the SSR `context` object to extract `<title>`, `<meta>`, or `<link>` tags in a React 19 environment, you should instead render these tags directly in your component tree. React 19 will hoist them natively. For `htmlAttributes` and `bodyAttributes`, the context and direct DOM manipulation remain relevant.
• gotcha Using `react-helmet-async` without `<HelmetProvider>` will lead to incorrect state management, especially in server-side rendering or concurrent environments, as it relies on the provider to encapsulate state per request. This can cause cross-request data leakage.
  Fix: Always wrap your React application with `<HelmetProvider>`, both on the client and server. For SSR, ensure you pass a unique `context` object to `<HelmetProvider>` for each request.
• gotcha The package is a fork of `react-helmet` specifically to address its thread-safety issues when performing asynchronous operations on the server. If migrating from `react-helmet`, ensure you replace all `Helmet.renderStatic()` calls with the `context` object extraction from `<HelmetProvider>`.
  Fix: When migrating from `react-helmet`, remove `Helmet.renderStatic()` calls and instead pass a `context` object to `<HelmetProvider>` during SSR. Extract the `helmet` object from this `context` after rendering.

Install

• npm install react-helmet-async npm
• yarn add react-helmet-async yarn
• pnpm add react-helmet-async pnpm

Imports

• Helmet
  wrong:

  import Helmet from 'react-helmet-async';

  correct:

  import { Helmet } from 'react-helmet-async';

  The default export was removed in version 1.0.0. Named import is required since then.
• HelmetProvider
  wrong:

  const { HelmetProvider } = require('react-helmet-async');

  correct:

  import { HelmetProvider } from 'react-helmet-async';

  Essential for encapsulating Helmet state, especially for SSR. Primarily designed for ESM usage.
• HelmetServerState (conceptual)
  wrong:

  Helmet.renderStatic();

  correct:

  const { helmet } = helmetContext;

  For server-side rendering, state is extracted from the `context` object passed to `HelmetProvider`, replacing the deprecated `renderStatic()` method from prior `react-helmet` versions. In React 19, the context will not be populated for `<title>`, `<meta>`, `<link>` as React handles them natively.

Quickstart

This quickstart demonstrates basic client-side usage of Helmet for managing document head attributes, title, meta, link, style, and script tags within a React application, wrapped in a HelmetProvider.

import React from 'react';
import { createRoot } from 'react-dom/client';
import { Helmet, HelmetProvider } from 'react-helmet-async';

const App = () => (
  <div>
    <Helmet>
      <html lang="en" amp />
      <title>My Awesome App</title>
      <meta name="description" content="A basic example of react-helmet-async." />
      <link rel="canonical" href="https://example.com/" />
      <style>{`body { background-color: #f0f0f0; }`}</style>
      <script type="application/ld+json">
        {
          "@context": "https://schema.org",
          "@type": "WebSite",
          "url": "https://example.com/",
          "name": "My Awesome App"
        }
      </script>
    </Helmet>
    <h1>Welcome to My Awesome App!</h1>
    <p>Check the document head for meta tags.</p>
  </div>
);

const rootElement = document.getElementById('app');
if (rootElement) {
  createRoot(rootElement).render(
    <HelmetProvider>
      <App />
    </HelmetProvider>
  );
} else {
  console.error('Root element #app not found!');
}