@xylabs/meta-server

Table of Contents

• @xylabs/meta-server
  • Table of Contents
  • Description
  • Install
  • Usage
    • Development
    • Deployment
    • Client
      • Live Share
  • Maintainers
  • License
  • Credits

Description

Express server for properly rendering HTML metadata on React sites when scraped/shared. Since React requires JS to execute in order to manipulate the DOM, page content and HTML metadata often looks different when viewed in a browser vs when scraped/shared. Likewise, client routes created via the History pushState API are client-side only and will return Not Found when requested to the server. The MetaServer attempts to ensure that shared/scraped links render the HTML just as it would be rendered when viewed in the browser. This is accomplished by intercepting route requests and rendering the HTML in headless Chrome then returning the resultant HTML instead of the typical React-hosting flow of just redirecting to the root of the site.

Install

The package should be installed under dependencies (not under devDependencies) as the server will be used for hosting & running the React App.

Using npm:

npm i --save @xylabs/meta-server

Using yarn:

yarn add @xylabs/meta-server

Usage

Development

The build output can be hosted/served via the MetaServer by running the included script. Configuration is available via

npm run start-meta

yarn start-meta

You can configure the root directory from which your app is served via the ENV VAR SERVE_DIRECTORY which defaults to './build' if not supplied

Deployment

To allow for containerized deployment the included script docker-build is provided which creates a production build of the app and outputs a container with the Meta Server which proxies the built app.

Client

• Add xy.config.json to the root of your build output (see sample below)

Sample xy.config.json

{
  liveShare: {
    exclude: ['/exclude/*'],
    include: ['/live-share-route/*'],
  },
}

Live Share

For LiveShare routes, pages are required to provide a meta tag with the property xyo:og:image with a content attribute that contains the URL of the preferred route for rendering the preview. The URL specified for the preview must be valid and lead to a route where an element with the ID 'preview-container' is present. The MetaServer wil:

• render the page rendered
• read the xyo:og:image attribute
• navigate to the URL provided in the xyo:og:image attribue
• wait for the DOM to contain an element with the ID preview-container
• snapshot the page and cache the image
• update the document head to point to the og:image (and associated properties like height/width) to point to the cached snapshot

HTTP Status Codes from React (Soft 404s)

By default, meta-server returns HTTP 200 for all SPA routes, even if the React app renders a "not found" page. To return a true HTTP status code (e.g. 404) for soft error pages, add an xy:status meta tag in your React app's error page:

<meta name="xy:status" content="404" />

For example, in a React component:

function NotFoundPage() {
  return (
    <>
      <Helmet>
        <meta name="xy:status" content="404" />
      </Helmet>
      <h1>Page Not Found</h1>
    </>
  )
}

When meta-server renders the page via Puppeteer (in Dynamic Share mode), it reads this meta tag and returns the specified HTTP status code instead of 200. This only applies to hard navigations (direct URL access, page refresh); client-side route changes within the SPA are unaffected.

Requirements:

• The route must be handled by Dynamic Share (configured via dynamicShare.pathFilter in xy.config.json). Dynamic Share uses Puppeteer to render the page, which is required to detect the meta tag.
• Live Share and Proxy Original modes do not support xy:status because they do not perform a full page render.

Supported status codes: Any valid HTTP status code (404, 410, 301, etc.)

Maintainers

• Arie Trouw (https://arietrouw.com)
• Joel Carter (https://joelbcarter.com)
• Matt Jones

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XY Labs