@lomray/react-head-manager

v2.2.5

Published

5 days ago

React meta tags manager with SSR and Suspense support.

0High
0Medium
0Low

matthew_patell

js meta tags react ssr suspense head manager title

React meta tags manager with SSR and Suspense support

npm GitHub

Getting started

The package is distributed using npm, the node package manager.

npm i --save @lomray/react-head-manager

WARNING: this package use @lomray/consistent-suspense for generate stable id's inside Suspense.

Usage

Pass a manager into your application rather than sharing a module-level instance across server requests.

import React from 'react';
import { ConsistentSuspenseProvider } from '@lomray/consistent-suspense';
import { MetaManagerProvider, Manager, Meta } from '@lomray/react-head-manager';

export const App = ({ manager }: { manager: Manager }) => (
  <ConsistentSuspenseProvider>
    <MetaManagerProvider manager={manager}>
      <Meta>
        <title>Example</title>
        <meta name="description" content="Description example" />
        <body data-id="test" />
      </Meta>
      <main>Example page</main>
    </MetaManagerProvider>
  </ConsistentSuspenseProvider>
);

For a client-rendered app on React 18 or newer, create one manager when mounting the application. The package also supports React 17, but react-dom/client and createRoot require React 18+:

import React from 'react';
import { createRoot } from 'react-dom/client';
import { Manager } from '@lomray/react-head-manager';
import { App } from './app';

const root = document.getElementById('root');

if (!root) {
  throw new Error('Missing #root element');
}

createRoot(root).render(<App manager={new Manager()} />);

Server rendering

Create a fresh manager for each request and pass it to both your application and the server helpers. Do not reuse one server manager across requests: it holds the tags and container state for that render.

The server helpers are the default export of @lomray/react-head-manager/server. MetaServer.inject(html, manager) inserts the collected tags into your HTML; MetaServer.getState(manager) returns state for the client manager. SSR also needs the corresponding hydration and Suspense setup; the client-only mount above is not an SSR hydration example.

That import path works through a bundler such as Vite. The published package defines no exports map (checked on 2.2.2), so native Node ESM cannot resolve the directory import and needs the file path instead: @lomray/react-head-manager/server/index.js.

The minimal SSR template shows the complete integration:

src/server.ts creates a manager per request and uses the server helpers.
src/client.ts constructs the client manager from the server state.
src/app.tsx supplies that manager to the provider.

Change tags order:

/**
 * Way 1
 */
const manager = new Manager();
manager.setTagsDefinitions({
  title: 1, // change order for title tag
  "meta[name='viewport']": 2, // change order for meta viewport tag
  meta: 100, // change for all meta tags
  script: 200, // change for all script tags
});

/**
 * Way 2
 */
<Meta>
  <title data-order={1}>Example</title>
  <meta data-order={3} name="description" content="Description example" />
  <meta data-order={2} name="keywords" content="test,key" />
</Meta>

/**
 * You can also use both...
 */

Explore demo app to more understand.

Workers and edge rendering

MetaServer.inject serves the static <head> of your HTML template as written. A tag the application does not override reaches the client verbatim, so inline handlers (<link rel="stylesheet" media="print" onload="this.media='all'">, <script onerror="...">), attribute casing and boolean attributes survive. Comments stay with the tag that follows them. Only tags replaced by a <Meta> from the application are rendered through React. Tags are still ordered by the manager (charset, viewport, title, base, meta, link, script, noscript, style; override with data-order). On hydration the client adopts the existing head nodes, including the tags of <Meta> components inside streamed Suspense boundaries, and only touches the tags it owns: a tag whose props differ from the server output is updated in place, and a tag with the same key survives navigation as the same node.

The @lomray/react-head-manager/server entry supports Cloudflare Workers and other non-DOM edge bundles, including Vite SSR with ssr.target: 'webworker'. MetaServer.inject and MetaServer.getState work without a document global or any HTML parser package.

Bundle size

The browser build reads the existing head from the DOM and ships no HTML parser. The server helper reads the template head with its own small tokenizer, so the package has no runtime dependencies.

Bugs and feature requests

Bug or a feature request, please open a new issue.

License

Made with 💚

Published under MIT License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme