Misc doc tweaks

[ci skip]
insin · Jan 25, 2017 · 214b8dd · 214b8dd
1 parent 1efe259
commit 214b8dd
Show file tree

Hide file tree

Showing 7 changed files with 80 additions and 64 deletions.
diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ npm install --save-dev nwb
 
 ## Quick Development
 
-For quick development with React, Inferno or Preact, use the global `react`, `inferno` or `preact` commands.
+For quick development with [React](https://facebook.github.io/react/), [Inferno](https://infernojs.org/) or [Preact](https://preactjs.com/), use the global `react`, `inferno` or `preact` commands.
 
 ```js
 import React, {Component} from 'react'
@@ -135,8 +135,8 @@ cd my-module/
 
 ## [Guides](/docs/guides/#table-of-contents)
 
-- [Quick Development with nwb](/docs/guides/QuickDevelopment.md)
-- [Developing React Apps with nwb](/docs/guides/ReactApps.md)
+- [Quick Development with nwb](/docs/guides/QuickDevelopment.md#quick-development-with-nwb)
+- [Developing React Apps with nwb](/docs/guides/ReactApps.md#developing-react-apps-with-nwb)
 - [Developing React Components and Libraries with nwb](/docs/guides/ReactComponents.md#developing-react-components-and-libraries-with-nwb)
 
 ## [Documentation](/docs/#table-of-contents)
@@ -145,6 +145,7 @@ cd my-module/
 - [Commands](/docs/Commands.md#commands)
   - [`react`](/docs/Commands.md#react)
   - [`nwb`](/docs/Commands.md#nwb)
+  - [`react`, `inferno` and `preact`](docs/guides/QuickDevelopment.md#quick-development-with-nwb)
 - [Configuration](/docs/Configuration.md#configuration)
   - [Configuration File](/docs/Configuration.md#configuration-file)
   - [Configuration Object](/docs/Configuration.md#configuration-object)

diff --git a/docs/Commands.md b/docs/Commands.md
@@ -125,7 +125,7 @@ The following commands require a [configuration file](/docs/Configuration.md) to
 
 ##### `nwb serve`
 
-Starts a development server which serves an app with hot module reloading.
+Starts a development server which serves an app with Hot Module Replacement.
 
 ```
 nwb serve [entry]
@@ -200,7 +200,7 @@ set NODE_ENV=development&& nwb build
 
 In production mode builds, the Babel [react-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types) transform will be used.
 
-When building React apps, you can also pass a `--preact` flag to configure Webpack to use [Preact](https://preactjs.com/) via the [`preact-compat`](https://github.com/developit/preact-compat) module, or an `--inferno` flag to configure Webpack to use [Inferno](https://infernojs.org/) via the [`inferno-compat`](https://github.com/infernojs/inferno/tree/master/packages/inferno-compat#readme) module.
+When building React apps, you can also pass a `--preact` flag to configure Webpack to use [Preact](https://preactjs.com/) via the [`preact-compat`](https://github.com/developit/preact-compat#readme) module, or an `--inferno` flag to configure Webpack to use [Inferno](https://infernojs.org/) via the [`inferno-compat`](https://github.com/infernojs/inferno/tree/master/packages/inferno-compat#readme) module.
 
 If your app and its dependencies are compatible, this can be a quick and easy way to reduce the size of your app.
 

diff --git a/docs/Features.md b/docs/Features.md
@@ -1,23 +1,24 @@
 ## Features
 
 - **A toolkit, not a boilerplate.**
-- Provides specific tooling for React apps and components, Preact apps, Inferno apps, and vanilla JS web apps and npm modules.
-- ES6 and JSX support.
-- Use future JavaScript features like object spreading now; TC39 Stage 2 and above features are enabled by default.
-- Default polyfills and configuration allow use of `Promise` (with rejection tracking enabled), `fetch`, `async`/`await`, generators and `Object.assign` in any browser.
-- Import CSS (and font resources), images and JSON into your JavaScript.
-- Autoprefixed CSS, so you don't need to write browser prefixes; you can also configure your own PostCSS plugins.
-- Plugin modules which add [Sass](https://github.com/insin/nwb-sass), [Less](https://github.com/insin/nwb-less) and [Stylus](https://github.com/insin/nwb-stylus) support without needing configuration.
+- Uses [Webpack](https://webpack.js.org/), [Babel](https://babeljs.io/) and [Karma](https://karma-runner.github.io/).
+- Provides tooling for [React](https://facebook.github.io/react/) apps and components, [Preact](https://preactjs.com/) apps, [Inferno](https://infernojs.org/) apps, and vanilla JS web apps and npm modules.
+- Use the latest JavaScript features (ES2015, ES2016, ES2017) and JSX.
+- Use future JavaScript features like object spreading now; [TC39](https://exploringjs.com/es2016-es2017/ch_tc39-process.html) Stage 2 and above features are enabled by default.
+- Default polyfills and configuration allow use of [`Promise`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) (with [rejection tracking](https://www.2ality.com/2016/04/unhandled-rejections.html) enabled), [`fetch()`](https://developer.mozilla.org/en/docs/Web/API/Fetch_API), [`async`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)/[`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await), [generators](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Statements/function*) and [`Object.assign()`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) in any browser.
+- Import CSS (and font resources) and images to be managed by Webpack.
+- [Autoprefixed](https://github.com/postcss/autoprefixer#autoprefixer-) CSS, so you don't need to write browser prefixes; you can also configure your own [PostCSS](https://postcss.org/) plugins.
+- Plugin modules which add support for the [Sass](https://github.com/insin/nwb-sass), [Less](https://github.com/insin/nwb-less) and [Stylus](https://github.com/insin/nwb-stylus) stylesheet languages.
 
 **Development / DX:**
 
-- Quick development commands which reduce the time from idea to running code.
-- Development server with Hot Module Reloading, and syntax error and React `render()` error overlays.
+- Quick development commands for React, Preact and Inferno which reduce the time from idea to running code.
+- Development server with Hot Module Replacement, and syntax error and React `render()` error overlays.
 - User-friendly reporting of build status and errors in the CLI (based on [create-react-app](https://github.com/facebookincubator/create-react-app)'s).
 - Prompts to continue with a different port if the intended dev server port is not available.
 - Express middleware for serving the same development Webpack build from your own server.
 - **Experimental:** Automatically install dependencies from npm without restarting your development server by using an `--auto-install` flag.
-- **Experimental:** Write destructured ES6 imports which transpile to cherry-picked imports for specific modules to keep your bundle size down.
+- **Experimental:** Write destructured ES module `import`s which transpile to cherry-picked imports for specific modules to keep your bundle size down.
 
 **Testing:**
 
@@ -32,18 +33,18 @@
 - Optimised Webpack build prepares JS, CSS and images for production, with deterministic filename hashes for long-term caching, and sourcemaps.
 - Production optimisations for React apps, including stripping of `propTypes`.
 - Automatic creation of a separate vendor bundle.
-- Flag to try a build which replaces React with [Preact](https://preactjs.com/) or [Inferno](https://infernojs.org/) for a much smaller payload.
+- Flag to try a build which replaces React with Preact or Inferno via a compatibility layer, for a much smaller payload.
 
 **Publishing:**
 
-- Builds components and modules for publishing to npm with ES5 (including CommonJS exports interop), ES6 modules and UMD builds.
-- Project skeletons include a package.json config `files` whitelist to avoid bloating your packages.
+- Builds components and modules for publishing to npm with ES5 (including CommonJS exports interop), ES modules and UMD builds.
+- Project skeletons include a package.json config `files` whitelist to avoid bloating your published package.
 - React component skeleton includes a demo app ready to develop and build using the same React app development setup.
 - React component `propTypes` are automatically wrapped with an environment check, for elimination from production builds.
 
 **Configuration:**
 
-- Use a single configuration file to customise Babel, Webpack, Karma and npm builds if you need to.
-- Declarative config for Webpack loader and plugin settings makes then easy to tweak.
+- Use a single [configuration file](https://github.com/insin/nwb/blob/master/docs/Configuration.md#configuration) to customise Babel, Webpack, Karma and npm builds if you need to.
+- [Declarative config for Webpack rules and plugin settings](https://github.com/insin/nwb/blob/master/docs/Configuration.md#webpack-configuration) makes then easy to tweak.
 - Convenience configuration for commonly-used features like Webpack aliases and expression replacements.
-- Compatibility configuration for libraries which commonly cause Webpack issues, e.g. bundling Moment.js with only specified locales.
+- Compatibility configuration for libraries which commonly cause Webpack issues, e.g. for bundling Moment.js with only specified locales.
diff --git a/docs/ImplementingPlugins.md b/docs/ImplementingPlugins.md
@@ -0,0 +1,38 @@
+## Implementing Plugins
+
+Plugins are implemented as npm packages which have names beginning with `'nwb-'`, which export a plugin configuration object.
+
+nwb will scan the current project's `package.json` for these modules, then import them and merge their configuration objects for use when generating configurations.
+
+### CSS Preprocessor Plugins
+
+CSS preprocessor plugins must export a configuration object in the following format:
+
+ ```js
+ {
+    cssPreprocessors: {
+      'preprocessor-id': {
+        test: /\.ext$/,
+        loader: 'absolute path to a webpack loader module.js',
+        // Other rule config, e.g. default options
+      }
+    }
+ }
+   ```
+
+The preprocessor id is critical - this will be used to generate names for the Webpack rules and loaders created for the preprocessor, which users can use in their `nwb.config.js` to apply configuration.
+
+----
+
+As a concrete example, this is a complete implementation of a Sass preprocessor plugin:
+
+```js
+module.exports = {
+  cssPreprocessors: {
+    sass: {
+      test: /\.s[ac]ss$/,
+      loader: require.resolve('sass-loader')
+    }
+  }
+}
+```
diff --git a/docs/Middleware.md b/docs/Middleware.md
@@ -23,7 +23,7 @@ Your app's version of the Express module must be passed as the first argument.
 - `config` - path to a config file *[default: nwb.config.js]*
 - `entry` - entry point for the app *[default: src/index.js]*
 - `install` - automatically install missing npm dependencies *[default: `false`]*
-- `reload` - reload the page if Hot Module Reloading is unsuccessful *[default: `false`]*
+- `reload` - reload the page if Hot Module Replacement is unsuccessful *[default: `false`]*
 
 #### Example
 

diff --git a/docs/Plugins.md b/docs/Plugins.md
@@ -6,58 +6,34 @@ Plugin modules provide additional functionality - if you have one installed in y
 
 CSS preprocessors convert styles in alternative style languages to CSS, with the resulting CSS being passed through the standard nwb CSS pipeline.
 
-- [nwb-less](https://github.com/insin/nwb-less) - adds processing of `.less` files which use [Less syntax](http://lesscss.org/)
-- [nwb-sass](https://github.com/insin/nwb-sass) - adds processing of `.scss` and `.sass` files which use [Sass syntax](http://sass-lang.com/)
-- [nwb-stylus](https://github.com/insin/nwb-stylus) - adds processing of `.styl` files which use [Stylus syntax](http://stylus-lang.com/)
+- [nwb-less](https://github.com/insin/nwb-less) - adds processing of `.less` files which use [Less syntax](http://lesscss.org/) with [less-loader](https://github.com/webpack-contrib/less-loader#readme).
+- [nwb-sass](https://github.com/insin/nwb-sass) - adds processing of `.scss` and `.sass` files which use [Sass syntax](http://sass-lang.com/) with [sass-loader](https://github.com/jtangelder/sass-loader#readme)
+- [nwb-stylus](https://github.com/insin/nwb-stylus) - adds processing of `.styl` files which use [Stylus syntax](http://stylus-lang.com/) with [stylus-loader](https://github.com/shama/stylus-loader#readme)
 
-e.g. if you want to use Sass in your project, install nwb-sass...
+#### Example: using the Sass plugin
+
+If you want to use Sass in your project, install nwb-sass...
 
 ```
 npm install --save-dev nwb-sass
 ```
 
-...and you can now import `.scss` or `.sass` files:
+...and you can now import `.scss` or `.sass` files from JavaScript modules:
 
 ```js
-require('./styles.scss')
+import './styles.scss'
 ```
 
-----
-
-### Implementing Plugins
-
-Plugins are implemented as npm packages which have names beginning with `'nwb-'`, which export a plugin configuration object.
-
-nwb will scan the current project's `package.json` for these modules, then import them and merge their configuration objects for use when generating configurations.
-
-#### Implementing CSS Preprocessors
-
-CSS preprocessor plugins must export a configuration object in the following format:
-
- ```js
- {
-    cssPreprocessors: {
-      'preprocessor-id': {
-        test: /\.ext$/,
-        loader: 'absolute path to a webpack loader module.js',
-        // Other rule config, e.g. default options
-      }
-    }
- }
-   ```
-
-The preprocessor id is critical - this will be used to generate names for the Webpack rules and loaders created for the preprocessor, which users can use in their `nwb.config.js` to apply configuration.
-
-----
-
-As a concrete example, this is a complete, working implementation of a Sass preprocessor plugin:
+The sass plugin's unique id is `sass` - you can use this in [`webpack.rules` config](/docs/Configuration.md#rules-object) to provide configuration options for sass-loader:
 
 ```js
 module.exports = {
-  cssPreprocessors: {
-    sass: {
-      test: /\.s[ac]ss$/,
-      loader: require.resolve('sass-loader')
+  webpack: {
+    rules: {
+      sass: {
+        data: '@import "_variables"',
+        includePaths: [path.resolve('src/styles')]
+      }
     }
   }
 }

diff --git a/docs/guides/ReactApps.md b/docs/guides/ReactApps.md
@@ -129,7 +129,7 @@ If there's an error in the `render()` method of a React component, it will be di
 
 ![](resources/react-serve-app-render-error.png)
 
-React Hot Module Reloading is enabled and will attempt to patch changes into your React components while maintaining their current state:
+A React-specific Hot Module Replacement handler is enabled and will attempt to patch changes into your React components while maintaining their current state:
 
 ![](resources/react-serve-app-hmr-js.gif)
 
@@ -415,7 +415,7 @@ app.listen(3000, function(err) {
 })
 ```
 
-For an complete example, see [nwb-react-tutorial](https://github.com/insin/nwb-react-tutorial/#nwb-react-tutorial), which uses nwb middleware to provide a development build for the comment box from [the React tutorial](https://facebook.github.io/react/docs/tutorial.html) from the same server it uses to implement the API.
+For a complete example, see [nwb-react-tutorial](https://github.com/insin/nwb-react-tutorial/#nwb-react-tutorial), which uses nwb middleware to provide a development build for the comment box from [the React tutorial](https://facebook.github.io/react/docs/tutorial.html) from the same server it uses to implement the API.
 
 > This is the way I use nwb in my Node.js projects at work, conditionally importing and using nwb's middleware based on `process.env.NODE_ENV`.
 
@@ -470,7 +470,7 @@ npm start -- --reload
 
 There are some changes which can't automatically be patched into a running React app by the [experimental implementation nwb is using](https://github.com/gaearon/react-transform-hmr#react-transform-hmr), or which need to be manually hooked up using Webpack's or Module Replacement API if you want to accept them.
 
-Passing a `--reload` flag will auto-reload the page when Webpack Hot Module Reloading gets stuck.
+Passing a `--reload` flag will auto-reload the page when Webpack Hot Module Replacement gets stuck.
 
 #### Automatically Install Missing Dependencies