Skip to content

adam-26/react-html-metadata

Repository files navigation

react-html-metadata

npm npm CircleCI branch Maintainability Test Coverage Conventional Commits

Introduction

This package provides a simple HTML template that supports metadata.

In isolation, this package is rather boring. However, this package provides the basis for implementing components that support SSR stream interface with HTML metadata.

You can see one example of using react-router v4 with streams and metadata here.

Internally, this package uses a slightly modified version of the excellent react-helmet to apply metadata. The modified version is react-cap, and it differs in that it does not use data-react-helmet attributes, instead it utilizes the React lifecycle to render metadata.

This provides 2 benefits over react-helmet:

  1. No data-react-helmet attributes
  2. It displays correctly in react dev-tools.

Future Enhancements

Install

// npm
npm install --save react-html-metadata

// yarn
yarn add react-html-metadata

Usage

// Complete list of exports
import Html, {
  Metadata,
  withMetadata,
  HtmlTag,
  HeadTag,
  BodyTag,
  METADATA_PROP_NAME
} from 'react-html-metadata';

const metadata = Metadata.createNew({
  title: 'Html Metadata Demo',
  htmlAttributes: { lang: 'en' },
  bodyAttributes: { className: 'root' },
  meta: [
    { charset: 'utf-8' }
  ],
  link: [
    { rel: 'stylesheet', href: '/static/css/app.css' }
  ]
});

class DemoApp extends React.Component {

  render() {
    <Html metadata={metadata} lastChild="This is rendered after the content">
      This is the HTML body content
    </Html>
  }
}

For a more detailed example, look at the example project, you can clone and run it

Accessing the Metadata context

import { withMetadata } from 'react-html-metadata';

class DemoMd extends React.Component {

  static propTypes = {
    metadata: PropTypes.object
  };

  render() {
    // ...
  }
}

export default withMetadata()(DemoMd)

IMPORTANT: Any component accessing the metadata context must be a child component of the <Html> component.

API

Html component props:

metadata

Optional, must be an instance of Metadata

lastChild

Optional, a React node, anything that can be rendered This can be used to serialize data before closing the </body> tag, you could:

  • serialize application state
  • serialize a redux store
render

Optional, a function (metadata, props) => {} for custom rendering

children

Optional, content rendered inside of the <body> tag.

Metadata:

Metadata.createNew(/* optional - metadata object */)

A factory function that creates a new metadata instance, optionally accepting metadata configuration.

Metadata.createForHydration(metadataState)

A factory function that creates a new metadata instance for client hydration, expects the server generated metadata state.

Metadata.createForServerStreamRender(metadataState)

A factory function that creates a new metadata instance for SSR stream rendering, optionally accepting metadata state.

Metadata properties

These are all from react-helmet

  • bodyAttributes: Object

  • htmlAttributes: Object

  • titleAttributes: Object

  • title: string

  • titleTemplate: string

  • base: Array<Object>

  • link: Array<Object>

  • meta: Array<Object>

  • noscript: Array<Object>

  • script: Array<Object>

  • style: Array<Object>

  • persist: boolean:

    • True to persist the metadata, once added it will never be removed.

withMetadata(metadataPropName?: string):

A HOC for accessing Metadata on the context. Accepts an optional param that defines the prop name the metadata will be assigned to.

See above for an example

Utilities

The following components can be used to customize rendering of the component. View the source for details.

HtmlTag

HeadTag

BodyTag

Example

There is an example project at /examples/ssr.

If you are modifying this package and want changes to apply when running the included example, after making changes you'll need to run the following command:

npm run localDeploy

Contribute

For questions or issues, please open an issue, and you're welcome to submit a PR for bug fixes and feature requests.

Before submitting a PR, ensure you run npm test to verify that your coe adheres to the configured lint rules and passes all tests. Be sure to include unit tests for any code changes or additions.

License

MIT

About

React HTML document template that supporting metadata

Resources

License

Stars

Watchers

Forks

Packages

No packages published