To help you get started, we've collected the most common ways that @shopify/react-html is being used within popular public projects.

Shopify / quilt / packages / react-server / src / render / render.tsx View on Github

logger.log(rendering);
          logger.log(resolving);
        },
        ...options,
      });
      applyToContext(ctx, networkManager);

      const immediateAsyncAssets = asyncAssetManager.used(
        AssetTiming.Immediate,
      );
      const [styles, scripts] = await Promise.all([
        assets.styles({name: 'main', asyncAssets: immediateAsyncAssets}),
        assets.scripts({name: 'main', asyncAssets: immediateAsyncAssets}),
      ]);

      const response = stream(
        
          {app}
        ,
      );

      ctx.set(Header.ContentType, 'text/html');
      ctx.body = response;
    } catch (error) {
      const errorMessage = `React server-side rendering error:\n${error.stack ||
        error.message}`;

      logger.log(errorMessage);
      ctx.status = StatusCode.InternalServerError;

      // eslint-disable-next-line no-process-env
      if (process.env.NODE_ENV === 'development') {

View more ways to use @shopify/react-html

@shopify/react-html

A collection of utilities for constructing an HTML document.

Installation

yarn add @shopify/react-html

Usage

This package exposes two entrypoints:

• @shopify/react-html: which contains code that can be used on server and client. Code in your app and client directories should import from this entrypoint.
• @shopify/react-html/server: which contains all of react-html, but also includes some features that are not safe to run in a browser context. Code in your server directory should import from this entrypoint.

> Note: because this package creates an HTML document, this package is only for applications that are server rendered in Node. Rails apps generally have Rails perform the render of the HTML document, so they do not benefit from any part of this library.

In your server middleware

Your server needs to construct an HTML document. To do this, you can use the Html component and render function from @shopify/react-html/server:

import React from 'react';
import {render, Html} from '@shopify/react-html/server';

import App from '../app';

export default function middleware(ctx) {
  ctx.body = render(
    
      
    ,
  );
}

If you want to make use of the serialization techniques documented below, you must also construct an HtmlManager instance, pass it to a `` component, and call @shopify/react-effect’s extract method:

// Somewhere in your server
import {extract} from '@shopify/react-effect/server';
import {
  render,
  Html,
  HtmlManager,
  HtmlContext,
} from '@shopify/react-html/server';

export default async function middleware(ctx) {
  const manager = new HtmlManager();
  const app = ;

  await extract(app, {
    decorate: (element) => (
      {element}
    ),
  });

  ctx.body = render({app});
}

You can also use the Script, Style, and Serialize components detailed in the API reference to manually construct a variety of tags, which you will typically insert into the document with the Html component’s headMarkup and bodyMarkup props.

In your application

In order for link, meta, and title tags to be updated as components are mounted and unmounted, you must render the HtmlUpdater component somewhere in your tree:

// Somewhere in app code

function App() {
  return (
    <>
      
      
    
  );
}

In your client entrypoint

Your client needs to rehydrate the React application. In development, it also needs to remove some of the temporary markup we create to prevent flashes of unstyled content. To do so, use the showPage function exported from @shopify/react-html:

import {hydrate} from 'react-dom';
import {showPage} from '@shopify/react-html';
import App from '../app';

hydrate(, document.querySelector('#app'));
showPage();

You do not need to create a Manager/ Provider component on the client.

In your application code

Some parts of your application code may have some form of state that must be rehydrated when the server-rendered page is loaded on the client. To do so, application code can use the useSerialized hook exported from @shopify/react-html.

useSerialized() accepts a single string argument for the identifier to use; this will help you find the serialized script tag if you need to debug later on. It also accepts a generic type argument for the type of the data that will be serialized/ available after deserialization.

The hook returns an array where the first entry is the serialized data (or undefined, if it was not found), and the second entry is a component that accepts a data prop that is a function that returns the data to serialize (or a promise for that data).

> Note: providing a promise for the data prop has a catch if you are using @shopify/react-effect to extract the serializations in server rendering: it expects that you will only provide a promise for the serialization if it can’t be returned synchronously. If you always return a promise, @shopify/react-effect will assume it always needs to do another render of the tree, which will lead to an infinite loop.

Here is a complete example, using @shopify/react-i18n’s support for async translations as the data that needs to be serialized:

import {useSerialized} from '@shopify/react-html';
import {I18nContext, Manager} from '@shopify/react-i18n';

interface Props {
  locale: string;
  children: React.ReactNode;
}

interface Data {
  locale: string;
  translations: ReturnType;
}

export default function I18n({locale, children}: Props) {
  const [serialized, Serialize] = useSerialized<data>('i18n');
  const {locale, translations} = serialized || {locale: explicitLocale};
  const manager = new Manager({locale, fallbackLocale: 'en'}, translations);

  return (
    &lt;&gt;
      {children}
       {
          const getData = () =&gt; ({
            locale: manager.details.locale,
            translations: manager.extract(),
          });

          return manager.loading ? manager.resolve().then(getData) : getData();
        }}
      /&gt;
    
  );
}

The rationale for this approach to handling serialization is available in our original proposal.

API reference

useSerialized()

See the example above for a full exploration of useSerialized’s API.

createSerializer()

createSerializer is a legacy API that has been deprecated by useSerialized(). For full documentation of this API, please refer to older versions of this document. createSerializer will be removed in the next major version of @shopify/react-html.

``

The `` component serves as a top level wrapper for a React application, allowing you to avoid needing any kind of server-side template. It is only available from the server entrypoint of this package (@shopify/react-html/server). The Html component accepts the following props:

• manager: a Manager instance. When provided, the Html component will extract all the information from this object and place it in an appropriate place in the document.
• children: the application. It will be rendered to a string and placed inside a div with an ID of app.
• locale: the language to use for the HTML lang attribute.
• styles: descriptors for any stylesheet link tags you want to include in the HEAD of the document.
• inlineStyles: descriptors for any style tags you want to include in the HEAD of the document.
• scripts: descriptors for any script tags you want to include in your document. All scripts passed to this property will be deferred by appending them to the end of the document. We encourage this as a default because it improves the initial rendering performance of your page.
• blockingScripts: descriptors for any script tags you want to include in the HEAD of the document. These will block HTML parsing until they are evaluated, so use them carefully.
• headMarkup: additional JSX to be embedded in the head of the document (after stylesheets and inline styles, but before blocking scripts).
• bodyMarkup: additional JSX to be embedded in the body of the document (before serialization markup and deferred scripts).

import {Html} from '@shopify/react-html/server';

const html = (
  
    
  
);

``

The component lets you render tags in your document dynamically as part of your react app. It supports all of the props of a basic link tag, but forces some properties to be the values needed for a stylesheet. In general, prefer the styles prop of the Html component instead of using this component explicitly.

import {Stylesheet} from '@shopify/react-html/server';

;

``

The `` component lets you render `