Skip to content

Latest commit

 

History

History
183 lines (133 loc) · 5.33 KB

README.md

File metadata and controls

183 lines (133 loc) · 5.33 KB
Raw

HTMLDocument

HTMLDocument

Version build status npm version

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