@shopify/react-html
Advanced tools
@shopify/react-html
A collection of utilities for constructing an HTML document.
$ yarn add @shopify/react-html
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.
Your server needs construct an HTML document. To do this, you can use the Html component and render function from @shopify/react-html/server:
import * as React from 'react';
import {render, Html} from '@shopify/react-html/server';
import App from '../app';
export default function middleware(ctx) {
ctx.body = render(
<Html>
<App />
</Html>,
);
}
If you want to make use of the serialization techniques documented below, you must also construct a Manager instance, pass it to a <Provider /> component, and call @shopify/react-effect’s extract method:
// in App.tsx
import {Manager, Provider} from '@shopify/react-html';
function App({htmlManager}: {htmlManager: Manager}) {
return <Provider manager={htmlManager}>Hello world!</Provider>;
}
// Somewhere in your server
import {extract} from '@shopify/react-effect/server';
import {render, Html, Manager} from '@shopify/react-html/server';
export default function middleware(ctx) {
const manager = new Manager();
const app = <App htmlManager={manager} />;
await extract(app);
ctx.body = render(<Html manager={manager}>{app}</Html>);
}
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.
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(<App />, document.querySelector('#app'));
showPage();
You do not need to create a Manager/ Provider component on the client.
Some parts of your application code may have some form of state that must be rehydrated when the server-rendered page is rehydrated on the client. To do so, application code can use the createSerializer function exported from @shopify/react-html.
createSerializer() 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 function returns a pair of components:
const {Serialize, WithSerialized} = createSerializer<string>('MyData');
// Would create components with the following types:
function Serialize({data}: {data(): string}): null;
function WithSerialized({
children,
}: {
children(data: string | undefined): React.ReactNode;
}): React.ReactNode;
The general pattern for using these components is to render the WithSerialized component as the top-most child of a component responsible for managing this state. Within the render prop, construct whatever stateful store or manager you need, using the data that was retrieved in cases where the serialization was found (on the browser, or on subsequent server renders). Finally, render the UI that depends on that stateful part, and a Serialize component that extracts the part that you you need to communicate between server and client.
Here is a complete example, using @shopify/react-i18n’s support for async translations as the data that needs to be serialized:
import {createSerializer} from '@shopify/react-html';
import {Provider, Manager} from '@shopify/react-i18n';
interface Props {
locale: string;
children: React.ReactNode;
}
const {Serialize, WithSerialized} = createSerializer<
ReturnType<Manager['extract']>
>('i18n');
export default function I18n({locale, children}: Props) {
return (
<WithSerialized>
{data => {
const manager = new Manager(
{locale: data ? data.locale : locale},
data && data.translations,
);
return (
<>
<Provider manager={manager}>{children}</Provider>
<Serialize
data={() => ({
locale: manager.details.locale,
translations: manager.extract(),
})}
/>
</>
);
}}
</WithSerialized>
);
}
The rationale for this approach to handling serialization is available in our original proposal.
<Html />The <Html> 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 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 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 = (
<Html
locale="fr"
styles={[{path: '/style.css'}]}
scripts={[{path: '/script.js'}]}
>
<App />
</Html>
);
<Style />The <Style /> component lets you render <link> 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 {Style} from '@shopify/react-html';
<Style
href="./some-style.css"
integrity="some-integrity-hash"
crossOrigin="anonymous"
/>;
<Script />The <Script /> component lets you render <script> tags in your document dynamically as part of your react app. It supports all the props of a basic script tag. In general, prefer the scripts prop of the Html component instead of using this component explicitly.
import {Script} from '@shopify/react-html';
<Script
src="./some-script.js"
integrity="some-integrity-hash"
crossOrigin="anonymous"
/>;
<Link />Renders a <link /> tag in the head with the specified attributes. On the server, links are recorded in the Manager and automatically applied to the Html component. On the client, the <link /> tags are updated in a deferred callback to minimize DOM manipulations.
The <Link /> component accepts any properties you would supply to a <link /> tag. If you are using this component to create a favicon, use the <Favicon /> component instead.
<Meta />Renders a <meta /> tag in the head with the specified attributes. This component uses the same approach to render these tags as detailed for the <Link /> component above.
The <Meta /> component accepts any properties you would supply to a <meta /> tag.
<Title />Renders a <title /> tag in the head with the specified attributes. If multiple <Title /> components are rendered in your app, the last one (usually, the most deeply nested) will be applied.
This component accepts a string child, which will be used to set the title of the page.
<Favicon />Renders a <link /> tag with the necessary props to specify a favicon. Accepts a source property that should be the image source for the favicon.
<Preconnect />Renders a <link /> tag that preconnects the browser to the host specified by the source prop. You can read more about preconnecting on Google’s guide to resource prioritization.
<Responsive />Renders a <Meta /> tag that specifies additional functionality and dimensions to mobile devices. Accepts a coverNotch property which allows the viewport to fill the device display, and an allowPinchToZoom property to the allow the app to be zoomed-in. Both properties default to true.
<AppleHomeScreen />Renders iOS-specific <Meta /> tags and <Link /> tags to specify additional visual information on how to display the app on iOS devices. Accepts an icons property as an array of image attributes to be used for the app‘s home screen icon. Also accepts a startUpImage url to render while the app is loading after being launched from the home screen.
<Serialize />The Serialize component takes care of rendering a script tag with a serialized version of the data prop. It is provided for incremental adoption of the createSerializer() method of generating serializations documented above.
render()The render() function creates a stringified version of the HTML document with an appropriate DOCTYPE. It is only available from the server entrypoint of this package (@shopify/react-html/server).
import {render, Html} from '@shopify/react-html/sever';
const markup = render(<Html>Hello world!</Html>);
showPage()This function encapsulates the logic for showing the page in development, where it is hidden on the initial render by default. You must call this function from your client entry point, usually right after hydrating your React app. It returns a promise that resolves after the document is guaranteed to be visible.
getSerialized<Data>()To help in migration, this function can imperatively return the parsed value of a serialization. It returns the data cast to whatever is passed for Data. It should only be called on the client.
FAQs
A component to render your React app with no static HTML
The npm package @shopify/react-html receives a total of 13,600 weekly downloads. As such, @shopify/react-html popularity was classified as popular.
We found that @shopify/react-html demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Elastic’s return to open source with the AGPL license has been met with skepticism, as many developers see it as a strategic move rather than a genuine effort to restore user trust and freedoms.
Security News
A new "revival hijack" supply chain attack targets deleted Python packages, with an estimated 22K packages at risk. Socket can detect and block hijacked packages that have added malicious code.
Product
We're introducing a new Analytics feature in the Socket dashboard so you can view changes in your organization's and repositories' alerts over time.