react-server-webpack-plugin

@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". :)

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/';
});