diff --git a/README.md b/README.md index f553ddd6..f46a1f87 100644 --- 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 index 86719e07..9fd8fffd 100644 --- 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 index 58ffa6dd..0802d6ea 100644 --- 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 new file mode 100644 index 00000000..570d6810 --- /dev/null +++ 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 index 7c32923d..f25463eb 100644 --- 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 index e2c74830..305ee55e 100644 --- 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 index ff923199..59489ed4 100644 --- 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