1 | # Server
|
2 | Easy creation and launch of web-server with standard configuration, that serves
|
3 | a ReactJS application with or without server-side rendering, supports
|
4 | development tools (Hot Module Reloading), and can be further configured for
|
5 | the needs of specific projects.
|
6 |
|
7 | **Why?** — Each ReactJS application demands a web-server, and there is
|
8 | a bunch of generic boilerplate code involved. Here is our solution to this,
|
9 | which allows to create a simple, but functional, web-server in a moment, and
|
10 | permits to further configurate it for specific use.
|
11 |
|
12 | *NOTE:* It is supposed that this server, even with zero configration, supports
|
13 | most standard ReactJS setups: i.e. with or without server-side rendering and/or
|
14 | Redux. However, the current code was spawned out from a specific codebase that
|
15 | used Redux and server-side rendering. Should you experience any problems in any
|
16 | other use case, don't hesitate to attract attention to your issues and propose
|
17 | fixes/enhancements!
|
18 |
|
19 | ### Details
|
20 | Technically, our server solution consists of three parts: `dist/server/renderer`
|
21 | takes care about the actual rendering of HTML template, injection of config and
|
22 | server-side rendered ReactJS markup; `dist/server/server` creates and configures
|
23 | ExpressJS server; and `dist/server` assemble them together, sets up and launches
|
24 | the native NodeJS server that exposes ExpressJS to the outside world.
|
25 |
|
26 | For the practical use, staring the server is as easy as:
|
27 | ```js
|
28 | import { server } from 'topcoder-react-utils`;
|
29 | import webpackConfig from 'config/webpack/production.js`;
|
30 |
|
31 | const options = {}; // A number of extra options can be provided here.
|
32 |
|
33 | server(webpackConfig, options);
|
34 | ```
|
35 |
|
36 | The `serverFactory(webpackConfig, options)` function initializes, and launches
|
37 | the server, and it returns a Promise that resolves to an object with two fields,
|
38 | `expressServer` and `httpServer` that contain the created and launched servers.
|
39 |
|
40 | The first argument of the factory, `webpackConfig` is the Webpack config used to
|
41 | build the frontend bundle: in production mode server takes out of it `context`,
|
42 | `publicPath`, and some other params; in development mode the entire config is
|
43 | necessary to run ExpressJS in development mode.
|
44 |
|
45 | The second argument, `options`, is optional; it allows to pass in the following
|
46 | props:
|
47 | - **`Application`** — *Component* — Optional. The root ReactJS
|
48 | component of the app. If provided, server will perform server-side rendering,
|
49 | and it will inject the rendered markup into the HTML template it serves.
|
50 | - **`devMode`** — *Boolean* — Optional. Specifies, whether the
|
51 | server should be launched in the development mode.
|
52 | - **`favicon`** — *String* — Optional. Path to the favicon to be
|
53 | served by the server.
|
54 | - **`logger`** — *Object* — Optional. The logger to be used for
|
55 | logging. Defaults to `console`, otherwise it is expected to provide the same
|
56 | interface. Note that `console` is not efficient for production use, because
|
57 | it is not async in NodeJS.
|
58 | - **`beforeRender`** — *Function(req, config)* — Optional. The hook to be
|
59 | executed right before the generation of HTML template of the page.
|
60 |
|
61 | **Arguments:**
|
62 | - **`req`** — *Object* — ExpressJS HTTP request;
|
63 | - **`config`** — *Object* — App config that server wants to inject
|
64 | into HTML page template;
|
65 |
|
66 | **Returns:** Promise that resolves to an object with the following fields:
|
67 | - **`configToInject`** — *Object* — Optional. The actual config
|
68 | object
|
69 | to be injected into the page. If omitted, the one proposed by the server
|
70 | will be used.
|
71 | - **`extraScripts`** — *String[]* — Additional script tags to be
|
72 | injected into the page.
|
73 | - **`store`** — *Object* — Redux store which state will be
|
74 | injected into HTML template as the initial state of the app.
|
75 | - **`onExpressJsSetup`** — *Function* — Custom setup of ExpressJS
|
76 | server. Express server instance will be passed in as the only argument to this
|
77 | function.
|
78 | - **`port`** — *Number|String* — The port to be used by the server.
|