1 | # `@shopify/react-server`
|
2 |
|
3 | [![Build Status](https://travis-ci.org/Shopify/quilt.svg?branch=master)](https://travis-ci.org/Shopify/quilt)
|
4 | [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md) [![npm version](https://badge.fury.io/js/%40shopify%2Freact-server.svg)](https://badge.fury.io/js/%40shopify%2Freact-server.svg)
|
5 |
|
6 | A simple library for React server-side rendering using [`@shopify/react-html`](https://github.com/Shopify/quilt/tree/master/packages/react-html).
|
7 |
|
8 | ## Table of contents
|
9 |
|
10 | 1. [Installation](#installation)
|
11 | 1. [Node usage](#node-usage)
|
12 | 1. [Rails usage](#rails-usage)
|
13 | 1. [Deployment](#deployment)
|
14 | 1. [Webpack plugin](#webpack-plugin)
|
15 | 1. [API](#api)
|
16 |
|
17 | ## Installation
|
18 |
|
19 | ```bash
|
20 | $ yarn add @shopify/react-server
|
21 | ```
|
22 |
|
23 | ## Rails Usage
|
24 |
|
25 | We provide a [gem](https://github.com/Shopify/quilt/blob/master/gems/quilt_rails/README.md#L2) to automagically setup a proxy controller for react-server.
|
26 |
|
27 | ## Node Usage
|
28 |
|
29 | Node apps require a server entry point that calls the `createServer` function. At the minimum, this function requires a `render` function that renders the main `<App />` component.
|
30 |
|
31 | ```tsx
|
32 | import React from 'react';
|
33 | import {createServer} from '@shopify/react-server';
|
34 | import {Context} from 'koa';
|
35 | import App from '../app';
|
36 |
|
37 | const app = createServer({
|
38 | port: process.env.PORT ? parseInt(process.env.PORT, 10) : 8081,
|
39 | ip: process.env.IP,
|
40 | assetPrefix: process.env.CDN_URL || 'localhost:8080/assets/webpack',
|
41 | render: (ctx: Context) => {
|
42 | const whatever = /* do something special with the koa context */;
|
43 | // any special data we add to the incoming request in our rails controller we can access here to pass into our component
|
44 | return <App server location={ctx.request.url} someCustomProp={whatever} />;
|
45 | },
|
46 | });
|
47 | export default app;
|
48 | ```
|
49 |
|
50 | If you already have an existing node server, you can opt in to using only the render middleware provided by this package. See `createRender()`.
|
51 |
|
52 | ## Webpack Plugin
|
53 |
|
54 | We also provide a [webpack plugin](./docs/webpack-plugin.md) to automatically generate the server and client entries for an application.
|
55 |
|
56 | ### Deployment (Shopify specific)
|
57 |
|
58 | For Shopifolk, we have a [walkthrough](https://platform-docs.docs.shopify.io/getting_started/rails-with-a-private-node-server.html) for getting an app ready to deploy.
|
59 |
|
60 | ## API
|
61 |
|
62 | ### `createServer()`
|
63 |
|
64 | Creates a full `Koa` server which renders an `@shopify/react-html` application.
|
65 |
|
66 | ```tsx
|
67 | import {createServer} from '@shopify/react-server';
|
68 | ```
|
69 |
|
70 | The `createServer` function takes an `Options` object of the following interface.
|
71 |
|
72 | ```tsx
|
73 | interface Options {
|
74 | // the port to bind
|
75 | port?: number;
|
76 | // the ip to run the application on
|
77 | ip?: string;
|
78 | // the full base url for the cdn if applicable
|
79 | assetPrefix?: string;
|
80 | // the name of the asset on the cdn, or a function of Koa.Context to a name
|
81 | assetName?: string | (ctx: Context) => string;
|
82 | // any additional Koa middleware to mount on the server
|
83 | serverMiddleware?: compose.Middleware<Context>[];
|
84 | // a function of `(ctx: Context, data: {locale: string}): React.ReactElement<any>`
|
85 | render: RenderFunction;
|
86 | // whether to run in debug mode
|
87 | debug?: boolean;
|
88 | // a function similar to the render option but specifically used to render error pages for production SSR errors
|
89 | renderError: RenderFunction;
|
90 | }
|
91 | ```
|
92 |
|
93 | It returns a running [Koa](https://github.com/koajs/koa/) server.
|
94 |
|
95 | ### `createRender()`
|
96 |
|
97 | Creates a Koa middleware which renders an `@shopify/react-html` application.
|
98 |
|
99 | ```tsx
|
100 | import {createRender} from '@shopify/react-server';
|
101 | ```
|
102 |
|
103 | The `createRender` function takes two arguments. The first is a render function that should return the main component at the top of the application tree in JSX. This function receives the full [Koa](https://github.com/koajs/koa/) server context which can be used to derive any necessary props to feed into the main component.
|
104 |
|
105 | The second argument is a subset of [`@shopify/react-effect#extract`](../react-effect/README.md#extract)'s options which are simply delegated to the `extract` call within the `createRender` middleware.
|
106 |
|
107 | #### Options
|
108 |
|
109 | - `afterEachPass?(pass: Pass): any` see [`@shopify/react-effect#extract`](../react-effect/README.md#extract)
|
110 |
|
111 | - `betweenEachPass?(pass: Pass): any` see [`@shopify/react-effect#extract`](../react-effect/README.md#extract)
|
112 |
|
113 | It returns a [Koa](https://github.com/koajs/koa/) middleware.
|