@shopify/react-server-webpack-plugin

A webpack plugin which generates "virtual" in-memory entrypoints for @shopify/react-server based applications. This plugin allows you to run a universal React application without needing any client/server-specific code.

Installation

$ yarn add @shopify/react-server-webpack-plugin

Usage

With sewing-kit

As of version 0.102.0 sewing-kit consumes this plugin by default if you have @shopify/react-server in your package.json.

For detailed instructions on usage with Rails and sewing-kit see the documentation for quilt_rails.

Without sewing-kit

First you will need to install all of the dependencies you'll need for your application

yarn add react react-dom
yarn add webpack @shopify/react-server @shopify/react-server-webpack-plugin @shopify/webpack-asset-metadata-plugin --dev

Since @shopify/react-server relies on @shopify/webpack-asset-metadata-plugin, you will need to setup both plugins in your webpack configuration. A simple starter (not production optimized) webpack setup is as follows:

// webpack.config.js

const {ReactServerPlugin} = require('@shopify/react-server-webpack-plugin');
const {AssetMetadataPlugin} = require('@shopify/webpack-asset-metadata-plugin');

const universal = {
  mode: 'development',
  optimization: {
    minimize: false,
  },
  plugins: [new AssetMetadataPlugin(), new ReactServerPlugin()],
};

const server = {
  ...universal,
  name: 'server',
  target: 'node',
  entry: './server',
  externals: [
    (context, request, callback) => {
      if (/node_modules/.test(context)) {
        return callback(null, `commonjs ${request}`);
      }
      callback();
    },
  ],
};

const client = {
  ...universal,
  name: 'client',
  target: 'web',
  entry: './client',
};

module.exports = [server, client];

By default, this plugin expects the entrypoint to your application to be in the root directory.

// index.jsx
import React from 'react';

export default function App() {
  return <div>I am an app</div>;
}

Next you can run webpack && node dist/server.js. When the server starts up you should see:

started react-server on localhost:PORT

If you point your browser at localhost:PORT you should see "I am an app". :)

Automatic Props

The plugin passes some props to your application automatically.

interface DefaultProps {
  /*
   The full WHATWG URL object for the initial request. On the client this will *not* update reactively. It is always the URL for the initial request.
  */
  url: URL;

  /*
   An object containing any data sent via the `x-quilt-data` header.
   This header is used by `quilt_rails` for sending data directly from ruby to React.
  */
  data: Record<string, any>;
}

These props are provided during both server-side and client-side rendering, so they can be used without any special logic around what environment your app is in.

These props can be used to feed initial data into your application for use with libraries such as react-router, as well as for simple app logic.

// index.jsx
import React from 'react';

export default function App({url, data}: {url: Url, data: Record<string, any>}) {
  const {href} = url;
  if (href.endsWith('/about')) {
    return <div>this is an about page</div>;
  }

  return (
    <div>
      I am an app, here are some items:
      <ul>
        {data.items.forEach(({content, id}) => (
          <li key={id}>{content}</li>;
        ))}
      </ul>
    </div>
  );
}

API

The plugin is exported as a named export.

import {ReactServerPlugin} from '@shopify/react-server-webpack-plugin';

It accepts a configuration object with the following interface:

interface Options {
  /*
   The base-path to use for the `client.js` and `server.js` virtual entry files,
   this should also be where your index.tsx/jsx is.

   default: '.'
  */

  basePath: string;

  /*
   The host to use when calling `createServer` from `@shopify/react-server`,
   this should also be where your index.tsx/jsx is.

   default: process.env.REACT_SERVER_IP || "localhost"
  */
  host: string;

  /*
    The port to use when calling `createServer` from `@shopify/react-server`

    default: process.env.REACT_SERVER_PORT || 8081
  */
  port: number;

  /*
   The assetPrefix to use when calling `createServer` from `@shopify/react-server`.

   default: process.env.CDN_URL || "localhost:8080/assets/webpack"
  */
  assetPrefix: string;
}

An example configuration for a sewing-kit app named cool-app might look like this:

new ReactServerPlugin({
  assetPrefix: process.env.CDN_URL || 'https://localhost:8080/webpack/assets/';
});