v0.2.3 - Server functionality added

Author: birdofpreyru

README.md

@@ -65,10 +65,16 @@ only need to call `adopt-dev-deps` again if you update
 ### <a name="utilities">Utilities</a>
 - [**Global Styles**](docs/global-styles.md) &mdash; Global styles necessary for
   a generic application;
+- [**Isomorphy**](docs/isomorphy-utils.md) &mdash; Collection of helpers to deal
+  with isomorphic aspects of the code;
+- [**Jest utils**](docs/jest-utils.md) &mdash; Collection of helpers to be used
+  in Jest tests code;
 - [**SCSS Mixins**](docs/scss-mixins.md) &mdash; Collection of useful style
   mixins;
-- [**Jest utils**](docs/jest-utils.md) &mdash; Collection of helpers to be used
-  in Jest tests code.
+- [**Server**](docs/server.md) &mdash; Easy creation and launch of web-server
+  with standard configuration, that serves a ReactJS application with or without
+  server-side rendering, supports development tools (Hop Module Reloading), and
+  can be further configured for the needs of specific projects.
 
 ### <a name="development">Development</a>
 For convenient development you can link this package into your host package:

__tests__/__snapshots__/index.js.snap

@@ -0,0 +1,20 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Exports expected stuff 1`] = `
+Object {
+  "Avatar": [Function],
+  "Button": [Function],
+  "Link": [Function],
+  "NavLink": [Function],
+  "ScalableRect": [Function],
+  "utils": Object {
+    "isomorphy": Object {
+      "buildTimestamp": [Function],
+      "isClientSide": [Function],
+      "isDevBuild": [Function],
+      "isProdBuild": [Function],
+      "isServerSide": [Function],
+    },
+  },
+}
+`;

__tests__/index.js

@@ -1,9 +1,5 @@
 import * as exports from '../src';
 
 test('Exports expected stuff', () => {
-  expect(exports).toHaveProperty('Avatar');
-  expect(exports).toHaveProperty('Button');
-  expect(exports).toHaveProperty('Link');
-  expect(exports).toHaveProperty('NavLink');
-  expect(exports).toHaveProperty('ScalableRect');
+  expect(exports).toMatchSnapshot();
 });

__tests__/shared/Avatar.jsx renamed to __tests__/shared/components/Avatar.jsx

@@ -1,6 +1,6 @@
 import Avatar from 'components/Avatar';
 import React from 'react';
-import { snapshot } from '../../jest-utils';
+import { snapshot } from 'utils/jest';
 
 const testTheme = {
   avatar: 'avatarClassName',

__tests__/shared/Button.jsx renamed to __tests__/shared/components/Button.jsx

@@ -0,0 +1,48 @@
+/* Helper for loading of tested module. */
+const m = () => require('utils/isomorphy');
+
+afterEach(() => {
+  delete global.BUILD_INFO;
+  delete global.BUILD_TIMESTAMP;
+  delete global.FRONT_END;
+  delete process.env.BABEL_ENV;
+  process.env.NODE_ENV = 'test';
+});
+
+beforeEach(() => jest.resetModules());
+
+test('Client-side detection', () => {
+  global.FRONT_END = 'true';
+  expect(m().isClientSide()).toBe(true);
+  expect(m().isServerSide()).toBe(false);
+});
+
+test('Server-side detection', () => {
+  expect(global.FRONT_END).toBeUndefined();
+  expect(m().isClientSide()).toBe(false);
+  expect(m().isServerSide()).toBe(true);
+});
+
+test('Dev code build detection', () => {
+  process.env.BABEL_ENV = 'development';
+  expect(m().isDevBuild()).toBe(true);
+  expect(m().isProdBuild()).toBe(false);
+});
+
+test('Prod code build detection', () => {
+  process.env.BABEL_ENV = 'production';
+  expect(m().isDevBuild()).toBe(false);
+  expect(m().isProdBuild()).toBe(true);
+});
+
+test('Build timestamp on client-side', () => {
+  global.BUILD_TIMESTAMP = 'DUMMY_TIMESTAMP';
+  global.FRONT_END = true;
+  expect(m().buildTimestamp()).toBe('DUMMY_TIMESTAMP');
+});
+
+test('Build timestamp on server-side', () => {
+  global.BUILD_INFO = { timestamp: 'DUMMY_TIMESTAMP' };
+  expect(global.FRONT_END).toBeUndefined();
+  expect(m().buildTimestamp()).toBe('DUMMY_TIMESTAMP');
+});

__tests__/shared/GenericLink.jsx renamed to __tests__/shared/components/GenericLink.jsx

@@ -88,8 +88,8 @@ module.exports = function configFactory(ops) {
         filename: '[name].css',
       }),
       new webpack.DefinePlugin({
-        BUILD_RNDKEY: JSON.stringify(buildInfo.rndkey),
-        'process.env': {
+        global: {
+          BUILD_RNDKEY: JSON.stringify(buildInfo.rndkey),
           BUILD_TIMESTAMP: JSON.stringify(buildInfo.timestamp),
           FRONT_END: true,
         },

__tests__/shared/Link.jsx renamed to __tests__/shared/components/Link.jsx

@@ -0,0 +1,47 @@
+# Isomorphy
+Collection of helpers to deal with isomorphic aspects of the code.
+
+**Why?** — Most of our ReactJS code should be isomorphic, i.e. it should
+be functional both when executed at client-side (in browser), and when executed
+at server-side (in NodeJS), without extra care of the caller. In some cases, it
+demands to explicitely check, where the code is executed, and proceed depending
+on that. This module provides functions that allow to do such checks, and to get
+some additional information about the currently running code.
+
+All functions provided by this module should be imported and used like:
+```js
+import { utils } from 'topcoder-react-utils';
+
+utils.isomorphy.isClientSide();
+```
+
+Note that `isClientSide()` and `isServerSide()` functions rely on the global
+`FRONT_END` variable being defined only inside JS bundle build for the frontend
+execution by our standard Wepback config for apps. It is assumed that this
+variable won't be present in NodeJS environment.
+
+`isDevBuild()` and `isProdBuild()` functions rely on `BABEL_ENV` environment
+variable, and they tell about the build-time configuration of the code, which
+should be the same at the client- and server-side to ensure proper server-side
+rendering. This is independent of `NODE_ENV` environment variable, which sets
+the runtime configuration of the app, e.g. the API keys and endpoints to call
+for development and production, etc.
+
+`buildTimestamp()` function  relies on the global `BUILD_TIMESTAMP` variable
+defined in the frontend JS bundle build by our standard Webpack congif for app;
+at the server-side it relies on our standard server to expose, via the global
+`BUILD_INFO` object, the build info about the bundle served by the server.
+
+### Provided Functions
+- **`buildTimestamp()`** — Returns build timestamp of the frontend JS
+  bundle, in form of ISO date/time string. At the server-side it will be the
+  timestamp of bundle being served by the server.
+- **`isClientSide()`** — Returns `true` if executed at client-side
+  (in browser); `false` otherwise.
+- **`isDevBuild()`** — Returns `true` if development version of the code
+  is running; `false` otherwise.
+- **`isProdBuild()`** — Returns `true` if the production version of the
+  code is running; `false` otherwise.
+  variable (`NODE_ENV`, in turns, determines runtime configuration of the app).
+- **`isServerSide()`** — Returns `true` if executed at the server-side
+  (in NodeJS); `false` otherwise.

__tests__/shared/NavLink.jsx renamed to __tests__/shared/components/NavLink.jsx

@@ -0,0 +1,72 @@
+# Server
+Easy creation and launch of web-server with standard configuration, that serves
+a ReactJS application with or without server-side rendering, supports
+development tools (Hot Module Reloading), and can be further configured for
+the needs of specific projects.
+
+**Why?** — Each ReactJS application demands a web-server, and there is
+a bunch of generic boilerplate code involved. Here is our solution to this,
+which allows to create a simple, but functional, web-server in a moment, and
+permits to further configurate it for specific use.
+
+*NOTE:* It is supposed that this server, even with zero configration, supports
+most standard ReactJS setups: i.e. with or without server-side rendering and/or
+Redux. However, the current code was spawned out from a specific codebase that
+used Redux and server-side rendering. Should you experience any problems in any
+other use case, don't hesitate to attract attention to your issues and propose
+fixes/enhancements!
+
+### Details
+Technically, our server solution consists of three parts: `dist/server/renderer`
+takes care about the actual rendering of HTML template, injection of config and
+server-side rendered ReactJS markup; `dist/server/server` creates and configures
+ExpressJS server; and `dist/server` assemble them together, sets up and launches
+the native NodeJS server that exposes ExpressJS to the outside world.
+
+For the practical use, staring the server is as easy as:
+```js
+import serverFactory from 'topcoder-react-utils/dist/server`;
+import webpackConfig from 'config/webpack/production.js`;
+
+const options = {}; // A number of extra options can be provided here.
+
+serverFactory(webpackConfig, options);
+```
+
+The `serverFactory(webpackConfig, options)` function initializes, and launches
+the server, and it returns a Promise that resolves to an object with two fields,
+`expressServer` and `httpServer` that contain the created and launched servers.
+
+The first argument of the factory, `webpackConfig` is the Webpack config used to
+build the frontend bundle: in production mode server takes out of it `context`,
+`publicPath`, and some other params; in development mode the entire config is
+necessary to run ExpressJS in development mode.
+
+The second argument, `options`, is optional; it allows to pass in the following
+props:
+- **`Application`** — *Component* — Optional. The root ReactJS
+  component of the app. If provided, server will perform server-side rendering,
+  and it will inject the rendered markup into the HTML template it serves.
+- **`devMode`** — *Boolean* — Optional. Specifies, whether the
+  server should be launched in the development mode.
+- **`favicon`** — *String* — Optional. Path to the favicon to be
+  served by the server.
+- **`logger`** — *Object* — Optional. The logger to be used for
+  logging. Defaults to `console`, otherwise it is expected to provide the same
+  interface. Note that `console` is not efficient for production use, because
+  it is not async in NodeJS.
+- **`beforeRender`** — *Function* — Optional. The hook to be
+  executed right before the generation of HTML template of the page. If given,
+  it will receive the HTTP request as its only argument, and
+  it should return a promise that resolves to an object with the following
+  fields (all are optional):
+  - **`config`** — *Object* — Config object to inject into the
+    template.
+  - **`extraScripts`** — *String[]* — Additional script tags to be
+    injected into the page.
+  - **`store`** — *Object* — Redux store which state will be
+    injected into HTML template as the initial state of the app.
+- **`onExpressJsSetup`** — *Function* — Custom setup of ExpressJS
+  server. Express server instance will be passed in as the only argument to this
+  function.
+- **`port`** — *Number|String* — The port to be used by the server.

__tests__/shared/ScalableRect.jsx renamed to __tests__/shared/components/ScalableRect.jsx

@@ -81,7 +81,7 @@ mutation of the config object.
     Also `resolve.symlinks` Webpack option is set to *false* to avoid problems
     with resolution of assets from packages linked with `npm link`.
 
-  - The following environment variables will be emulated inside the output
+  - The following global variables will be emulated inside the output
     JS bundle:
     - **`BUILD_RNDKEY`** — A random 32 bit key that can be used
       for encryption, it is set just as a global variable accessible in