HTMLDocument
HTMLDocument is a foundational React component useful for rendering full html documents on the server.
You'll love HTMLDocument if:
- You love (or would love) to use React to render full documents on the server without the need for templates, view engines, or static files.
- You want to render documents in a way that makes it really easy to share state between server and client for hydrating client apps during mounting.
It provides a convenient and simple api for rendering common html tags such as title, meta, stylesheets, and scripts. In addition, it has universal/isomorphic-friendly features such as server state serialization, and support for static and non-static pages.
HTMLDocument is well tested and currently used in production on some of our web projects at Venmo.
Installation
To install the stable version:
npm install --save react-html-document
This assumes that youโre using npm.
Examples
Basic static page
import HTMLDocument from 'react-html-document';
import ReactDOMServer from 'react-dom/server';
const doc = (
<HTMLDocument title="My Page">
<h1>Hello World</h1>
</HTMLDocument>
);
ReactDOMServer.renderToStaticMarkup(doc);Renders to:
<html>
<head>
<title>My Page</title>
</head>
<body>
<div id="app">
<h1>Hello World</h1>
</div>
</body>
</html>
Static page with scripts, stylesheets, and meta tags
import HTMLDocument from 'react-html-document';
import ReactDOMServer from 'react-dom/server';
const doc = (
<HTMLDocument
title="My Page"
scripts={['/scripts/main.js']}
stylesheets={['/styles/styles.css']}
metatags={[
{ name: 'description', content: 'My description' }
]} >
<div>My App</div>
</HTMLDocument>
);
ReactDOMServer.renderToStaticMarkup(doc);Renders to:
<html>
<head>
<link rel="stylesheet" href="/styles/styles.css">
<meta name="description" content="My Description">
<title>My Page</title>
</head>
<body>
<div id="app">
<div>My App</div>
</div>
<script src="/scripts/main.js">
</body>
</html>
Using Universal state
import HTMLDocument from 'react-html-document';
import ReactDOMServer from 'react-dom/server';
const state = { user: "X" };
const doc = (
<HTMLDocument
title="My Page with Universal State"
universalState={state}>
</HTMLDocument>
);
ReactDOMServer.renderToStaticMarkup(doc);Renders to:
<html>
<head>
<title>My Page with Universal State</title>
</head>
<body>
<div id="app"></div>
<script id="__HTMLDOCUMENT__UNIVERSAL_STATE" type="application/json">
{ user: "X" }
</script>
</body>
</html>
HTMLDocument also provides a function to make this even easier:
// from the client
import { getUniversalState } from 'react-html-document';
const state = getUniversalState(); // { user: "X"}API
| Prop | Type | Details | Default |
|---|---|---|---|
title |
string | Title for the document. | '' |
metatags |
array | A list of meta tag attributes. | [ ] |
scripts |
array | A list of scripts in one of three forms: string paths 'mysite.com/script.js', script src objects { src: 'mysite.com/script.js' } or inline scripts { inline: 'var x = 1;' } |
[ ] |
stylesheets |
array | A list of stylesheet in one of three forms: string paths 'mysite.com/styles.css', style href objects { href: 'mysite.com/styles.css' } or inline styles { inline: 'body { color: '#333' }' } |
[ ] |
universalState |
object | Contains current server state that will be rendered into a script tag of type application/json on the page. Helpful for re-mounting with props on the client in universal apps. When not using it, children will be rendered statically. |
null |
childrenContainerId |
string | The id for the dom element that contains the children nodes. | 'app' |
favicon |
string | URL to your favicon. | '' |
htmlAttributes |
object | Attributes that you'd like to use on the html tag. | { } |
Development
Please take a look at package.json for available npm scripts.
For starting a dev server: npm run dev
For running mocha tests: npm test
For compiling src directory into dist directory with babel: npm run build
For linting with eslint: npm run lint
Contributing
We'd love for you to contribute.
Please open PRs from your fork to master. Keep in mind that we're using the eslint linter and the airbnb configuration for it. Rebase and squash when appropriate.
Versioning
This project adheres to Semantic Versioning.
License
MIT