Updated Babel configs and docs, added ESLint config

Author: birdofpreyru

README.md

@@ -1,11 +1,33 @@
 # Topcoder React Utils
-[Topcoder](https://www.topcoder.com) collection of generic ReactJS configurations, components and utilities to be shared between all internal and external ReactJS projects developed by Topcoder community.
+The [Topcoder](https://www.topcoder.com) collection of generic ReactJS configurations, components and utilities to be shared between all internal and external ReactJS projects developed by the Topcoder community.
 
-### Documentation
-This package provides: various configuration files that helps to unify configuration of various applications created at Topcoder, ReactJS components and utilities (non-react classes and functions)  that help to solve various typical problems in the same pattern accross all our apps.
+### Installation
+Install this package as
+```
+$ npm install --save topcoder-react-utils
+```
+
+You are done if you will use only components and utilities provided by this package. If you are to use configurations, you must also install peer dependencies. If you like to explicitly add them to the `package.json` of your project do
+```
+$ npm install -g install-peerdeps
+$ install-peerdeps topcoder-react-utils
+```
+
+Alternatively, you can do
+```
+$ npm install --save install-peerdeps
+```
+
+then add to your `package.json` the following script:
+```json
+"postinstall": "install-peerdeps -S topcoder-react-utils"
+```
+
+Now, in both cases, `$ npm install` will install all necessary dependencies, but in the second case they won't be stored into your `package.json`.
 
 #### Configurations
-- [**Babel Configurations**](docs/babel-config.md) — Standard configurations for [Babel](https://babeljs.io/)
+- [**Babel Configurations**](docs/babel-config.md) — Standard configurations for [Babel](https://babeljs.io/);
+- [**ESLint Configurations**](docs/eslint-config.md) — Standard configurations for [ESLint](https://eslint.org/).
 
 #### Components
 *To be added*

config/babel/node-ssr.js

@@ -0,0 +1,43 @@
+/* Babel preset for NodeJS build with support of server-side JSX rendering. */
+
+const _ = require('lodash');
+const config = _.cloneDeep(require('./webpack'));
+
+const cssModulesTransformPluginOps = {
+  extensions: ['.css', '.scss'],
+};
+
+const transformAssetsPluginOptions = {
+  extensions: ['gif', 'jpeg', 'jpg', 'png'],
+};
+
+config.plugins = config.plugins.concat([
+  'dynamic-import-node',
+  ['transform-assets', transformAssetsPluginOptions],
+  [ 'css-modules-transform', cssModulesTransformPluginOps ],
+]);
+
+const moduleResolverPluginOps
+  = config.plugins.find(x => x[0] === 'module-resolver')[1];
+
+moduleResolverPluginOps.transformFunctions = ['resolveWeak'];
+
+switch (process.env.BABEL_ENV) {
+  case 'development':
+    _.pull(config.plugins, 'react-hot-loader/babel');
+    cssModulesTransformPluginOps.generateScopedName = '[path][name]___[local]';
+    break;
+  case 'production':
+    cssModulesTransformPluginOps.generateScopedName = '[hash:base64:6]';
+    break;
+  case 'test':
+    cssModulesTransformPluginOps.generateScopedName = '[path][name]___[local]';
+    break;
+}
+
+module.exports = (apt, ops) => {
+  const baseAssetsOutputPath = ops.baseAssetsOutputPath || '';
+  transformAssetsPluginOptions.name
+    = `${baseAssetsOutputPath}/images/[hash].[ext]`;
+  return config;
+};

config/babel/node-ssr.json

@@ -0,0 +1,44 @@
+/* Babel preset for the Webpack build. */
+
+const envPresetOps = {};
+
+const reactCssModulesPluginOps = {
+  filetypes: {
+    '.scss': {
+      syntax: 'postcss-scss',
+    }
+  }
+};
+
+const config = {
+  presets: [
+    ['env', envPresetOps],
+    'react',
+    'stage-2',
+  ],
+  plugins: [
+    ['module-resolver', {
+      extensions: ['.js', '.jsx'],
+      root: [
+        './src/shared',
+        './src',
+      ],
+    }],
+    'inline-react-svg',
+    'transform-runtime',
+    ['react-css-modules', reactCssModulesPluginOps],
+  ],
+};
+
+switch (process.env.BABEL_ENV) {
+  case 'development':
+    reactCssModulesPluginOps.generateScopedName = '[path][name]___[local]';
+    config.plugins.push('react-hot-loader/babel');
+    break;
+  case 'production':
+    reactCssModulesPluginOps.generateScopedName = '[hash:base64:6]';
+    break;
+  default:
+}
+
+module.exports = config;

config/babel/webpack.js

@@ -0,0 +1,9 @@
+{
+  "extends": "airbnb",
+  "parser": "babel-eslint",
+  "settings": {
+    "import/resolver": {
+      "babel-module": {}
+    }
+  }
+}

config/babel/webpack.json

@@ -1,46 +1,66 @@
 # Babel Configurations
 Standard configurations for [Babel](https://babeljs.io/).
 
-**Why?** — We use Babel to support latest JavaScript specifications in our projects, and to allow for some fancy features in our code. The standard Babel configurations help to ensure that selected code patterns are supported in all of our apps.
+**Why?** — We use Babel to support latest JavaScript specifications in our projects, and to allow for some fancy features in our code. The standard Babel configurations ensure that the same code patterns are supported in all of our apps.
 
 Several Babel configurations are provided by this package:
 
-[**config/babel/webpack.json**](#webpack) — Babel config to use for JS and JSX files compilation during the Webpack build process;
+- [**config/babel/node-ssr**](#node-ssr) — Babel configuration for NodeJS compilation of JS and JSX modules (server-side ReactJS rendering);
 
-[**config/babel/node-ssr.json**](#node-ssr) — Server-side configuration with support of server-side rendering;
+- [**config/babel/webpack**](#webpack) — Babel configuration for Webpack compilation of JS and JSX modules.
 
-To use any of these configurations in your code use `extend` Babel option in your `.babelrc` file, or whenever you need it, e.g.
+Use them as presets in your `.babelrc`, e.g.
 ```json
 {
-  "extend": "topcoder-react-utils/config/babel/node-ssr.json"
+  "presets": ["topcoder-react-utils/config/babel/node-ssr"]
 }
 ```
-This way you can also easily tune some of Babel options in the way specific to your project; however if you feel that an option change you need is necessary for any generic react-based project, consider to submit an update to the configuration provided by `topcoder-react-utils`.
+
+To set options provided by a preset:
+```json
+{
+  "presets": [
+    ["topcoder-react-utils/config/babel/node-ssr", {
+      "someOption": "optionValue"
+    }]
+  ]
+}
+```
+
+As the presets are JS modules, you can also wrap them into your own JS code to create a special preset that customizes Babel configuration in any necessary way. If you feel that the modification you need is useful for any generic ReactJS app, feel free to open GitHub issue ticket to discuss an update of our default configurations.
+
+These presets may behave differently in different Babel environments. You can set the environment with `BABEL_ENV` environment variable, or with `forceEnv` option of the Webpack's `babel-loader`.
 
 ### Configuration Details
 
-- <a name="webpack">**`config/babel/webpack.json`**</a> &mdash; Babel config to use for JS and JSX files compilation during the Webpack build process;
+- <a name="node-ssr">**`config/babel/node-ssr.json`**</a> &mdash; Babel configuration for NodeJS compilation of JS and JSX modules (server-side ReactJS rendering);
 
   - Presets: [env](https://www.npmjs.com/package/babel-preset-env), [react](https://www.npmjs.com/package/babel-preset-react), [stage-2](https://www.npmjs.com/package/babel-preset-stage-2);
 
-  - Uses [`babel-plugin-react-css-modules`](https://www.npmjs.com/package/babel-plugin-react-css-modules) to transform `styleName` props of ReactJS components into `className` props. A style name is transformed into: (i) `.path-to-the-stylesheet-and-stylesheet-file-name___original-style-name` class in the *development* Babel environment; (ii) `.6-symbols-hash-of-the-style` in the *production* environment. The class names generated in the first cases are verbose, thus good for debugging; and in the second case they are compact which results in smaller size of JS and CSS bundles.
+  - Uses [`babel-plugin-css-modules-transform`](https://www.npmjs.com/package/babel-plugin-css-modules-transform) to convert CSS and SCSS imports into objects with keys and values being the original and transformed class names. The transformed class names will match the class names generated by the `babel-plugin-react-css-modules` plugin, mentioned below;
 
-  - Uses [`babel-plugin-inline-react-svg`](https://www.npmjs.com/package/babel-plugin-inline-react-svg) to embed imported SVG files into complied JS code;
+  - Uses [`babel-plugin-dynamic-import-node`](https://www.npmjs.com/package/babel-plugin-dynamic-import-node) to support dynamic `import(..)` statemens;
 
-  - Uses [`babel-plugin-transform-runtime`](https://ww.npmjs.com/package/babel-plugin-transform-runtime) to generate more optimal JS bundles;
+  - Uses [`babel-plugin-inline-react-svg`](https://www.npmjs.com/package/babel-plugin-inline-react-svg) to embed imported SVG files into the complied JS modules;
 
-  - Uses [`babel-plugin-module-resolver`](https://www.npmjs.com/package/babel-plugin-module-resolver) to setup the following paths as the roots for resolution of relative imports: `./src/shared`, `./src`;
+  - Uses [`babel-plugin-module-resolver`](https://www.npmjs.com/package/babel-plugin-module-resolver) to setup the following paths as the roots for resolution of relative imports: `./src/shared`, `./src`. It will also apply path resolution to the first argument of `resolveWeak(..)` functions encountered in the compiled code;
+
+  - Uses [`babel-plugin-react-css-modules`](https://www.npmjs.com/package/babel-plugin-react-css-modules) to transform `styleName` props of ReactJS components into globally unique `className` props. Generated class names are verbose in *development* and *test* Babel environment, for the ease of debugging; and they are short 6-symbols hashes in *production* Babel environment, for compactness of the compiled JS and CSS modules;
+
+  - Uses [`babel-plugin-tranform-assets`](https://www.npmjs.com/package/babel-plugin-transform-assets) to convert GIF, JPEG, JPG, and PNG imports into `/images/[FILE_HASH].[FILE_EXTENSION]` URL strings. Use the **`baseAssetsOutputPath`** preset option to prefix generated paths with an arbitrary path;
 
-  - Uses [`react-hot-loader/babel`](https://www.npmjs.com/package/react-hot-loader) to support hot module reloading in *development* environment.
+  - Uses [`babel-plugin-transform-runtime`](https://www.npmjs.com/package/babel-plugin-transform-runtime) to optimized complied JS modules (it externalizes references to helpers and builtins, automatically polyfilling the code without polluting globals).
 
-- <a name="node-ssr">**`config/babel/node-ssr.json`**</a> &mdash; Server-side configuration with support of server-side rendering. It extends [`config/babel/webpack.json`](#webpack) configuration with the following:
+- <a name="webpack">**`config/babel/webpack`**</a> &mdash; Babel configuration for Webpack compilation of JS and JSX modules.
 
-  - In the *test* Babel environment [`babel-plugin-react-css-modules`](https://www.npmjs.com/package/babel-plugin-react-css-modules) transforms a style name into `.path-to-the-stylesheet-___stylesheet-file-name__origina-style-name___5-symbols-hash-of-the-style` class. Resuling class names are verbose and good for debugging, the difference from *development* environment is for historic reasons.
+  - Presets: [env](https://www.npmjs.com/package/babel-preset-env), [react](https://www.npmjs.com/package/babel-preset-react), [stage-2](https://www.npmjs.com/package/babel-preset-stage-2);
+
+  - Uses [`babel-plugin-inline-react-svg`](https://www.npmjs.com/package/babel-plugin-inline-react-svg) to embed imported SVG files into the complied JS modules;
 
-  - Uses [`babel-plugin-css-modules-transform`](https://www.npmjs.com/package/babel-plugin-css-modules-transform) to convert CSS and SCSS imports into objects with keys and values being the original and generated class names. The class names are generated by the same rules being used to transform style names into classes;
+  - Uses [`babel-plugin-module-resolver`](https://www.npmjs.com/package/babel-plugin-module-resolver) to setup the following paths as the roots for resolution of relative imports: `./src/shared`, `./src`;
 
-  - Uses [`babel-plugin-tranform-assets`](https://www.npmjs.com/package/babel-plugin-transform-assets) to convert GIF, JPEG, JPG, and PNG imports into URL strings like `/images/hash-of-the-asset-file.original-file-extension`, where `/images/` is a fixed path prefix;
+  - Uses [`babel-plugin-react-css-modules`](https://www.npmjs.com/package/babel-plugin-react-css-modules) to transform `styleName` props of ReactJS components into globally unique `className` props. Generated class names are verbose in *development* and *test* Babel environment, for the ease of debugging; and they are short 6-symbols hashes in *production* Babel environment, for compactness of the compiled JS and CSS modules;
 
-  - Uses [`babel-plugin-dynamic-import-node`](https://www.npmjs.com/package/babel-plugin-dynamic-import-node) to support dynamic `import(..)` statement;
+  - Uses [`react-hot-loader/babel`](https://www.npmjs.com/package/react-hot-loader) to support hot module reloading in the *development* Babel environment;
 
-  - Avoids using [`react-hot-loader/babel`](https://www.npmjs.com/package/react-hot-loader) in the *development* Babel environment.
+  - Uses [`babel-plugin-transform-runtime`](https://www.npmjs.com/package/babel-plugin-transform-runtime) to optimized complied JS modules (it externalizes references to helpers and builtins, automatically polyfilling the code without polluting globals).

config/eslint/default.json

@@ -0,0 +1,18 @@
+# ESlint Configurations
+Standard configurations for [ESLint](https://eslint.org/).
+
+**Why?** — We use ESLint for quality control of our code. The standard ESLint configurations ensure that we use the same rules across all our projects.
+
+At the moment, a single ESLint configuration is provided by this package:
+- [**config/eslint/default**](#default) — Default ESLint configuration.
+
+Under the hood it matches the standard [AirBnB ESLint](https://www.npmjs.com/package/eslint-config-airbnb) config, and just adds a few plugins to ensure that ESLint properly cooperates with Babel to understand JS and JSX constructs we use in our code.
+
+To use it just create the following `.eslintrc`:
+```json
+{
+  "extends": "topcoder-react-utils/config/eslint/default"
+}
+```
+
+`.eslintrc` allows you to further modify ESLint configuration, but it is not recommended without a very good and special reason.