From 0ef86792515a0a2d069e46d57981e4c85208aed8 Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Wed, 15 Feb 2017 20:36:06 -0600 Subject: [PATCH] Docs: Mocha, Jest intro --- docs/presets/neutrino-preset-jest/README.md | 165 ++++++++++++++- docs/presets/neutrino-preset-mocha/README.md | 167 ++++++++++++++- docs/presets/neutrino-preset-node/README.md | 212 ++++++++++++++++++- docs/presets/neutrino-preset-react/README.md | 5 + docs/presets/neutrino-preset-web/README.md | 1 + 5 files changed, 547 insertions(+), 3 deletions(-) diff --git a/docs/presets/neutrino-preset-jest/README.md b/docs/presets/neutrino-preset-jest/README.md index 48a7ad3..12e37a7 100644 --- a/docs/presets/neutrino-preset-jest/README.md +++ b/docs/presets/neutrino-preset-jest/README.md @@ -1 +1,164 @@ -# heading +# Neutrino Jest Preset [![NPM version][npm-image]][npm-url] + +`neutrino-preset-jest` is a Neutrino preset that supports testing JavaScript projects with the Jest test runner. + +## Features + +- Zero upfront configuration necessary to start testing +- Babel compilation that compiles your tests using the same Babel options used by your source code +- Easily extensible to customize your testing as needed + +## Requirements + +- Node.js v6.9+ +- Yarn or npm client +- Neutrino v4, Neutrino build preset + +## Installation + +`neutrino-preset-jest` can be installed via the Yarn or npm clients. Inside your project, make sure +`neutrino` and `neutrino-preset-jest` are development dependencies. You will also be using +another Neutrino preset for building your application source code. + +#### Yarn + +```bash +❯ yarn add --dev neutrino-preset-jest +``` + +#### npm + +```bash +❯ npm install --save-dev neutrino-preset-mocha +``` + +## Project Layout + +`neutrino-preset-jest` follows the standard [project layout](/project-layout.md) specified by Neutrino. This +means that by default all project test code should live in a directory named `test` in the root of the +project. Test files end in either `_test.js` or `.test.js`. + +## Quickstart + +After adding the Jest preset to your Neutrino-built project, add a new directory named `test` in the root of the +project, with a single JS file named `simple_test.js` in it. + +```bash +❯ mkdir test && touch test/simple_test.js +``` + +Edit your `test/simple_test.js` file with the following: + +```js +describe('simple', () => { + it('should be sane', () => { + expect(!false).toBe(true); + }); +}); +``` + +Now edit your project's package.json to add commands for testing your application. In this example, +let's pretend this is a Node.js project: + +```json +{ + "scripts": { + "test": "neutrino test --presets neutrino-preset-node neutrino-preset-mocha" + } +} +``` + +Run the tests, and view the results in your console: + +#### Yarn + +```bash +❯ yarn test + + simple + ✓ should be sane + + + 1 passing (426ms) + +✨ Done in 4.17s. +``` + +#### npm + +```bash +❯ npm test + + simple + ✓ should be sane + + + 1 passing (409ms) +``` + +To run tests against files from your source code, simply import them: + +```js +import thingToTest from '../src/thing'; +``` + +## Executing single tests + +By default this preset will execute every test file located in your test directory ending in `_test.js`. +Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests. + +## Customizing + +To override the test configuration, start with the documentation on [customization](/customization/README.md). +`neutrino-preset-mocha` creates some conventions to make overriding the configuration easier once you are ready to make +changes. + +### Rules + +The following is a list of rules and their identifiers which can be overridden: + +- `compile`: Compiles JS files from the `test` directory using Babel. Contains a single loader named `babel`. + +### Simple customization + +By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above, +you can override and augment the build directly from package.json. + +### Advanced configuration + +By following the [customization guide](/customization/advanced.md) and knowing the rule, and loader IDs above, +you can override and augment testing by creating a JS module which overrides the config. + +You can modify Mocha settings by overriding the preset with any options Mocha accepts. This is stored in the +`neutrino.custom.mocha` object. + +_Example: Switch the test reporter from the default `spec` to `nyan`:_ + +```js +module.exports = neutrino => { + neutrino.custom.mocha.reporter = 'nyan'; +}; +``` + +```bash +❯ yarn test +yarn test v0.19.1 +$ node_modules/neutrino/bin/neutrino test + 1 -__,------, + 0 -__| /\_/\ + 0 -_~|_( ^ .^) + -_ "" "" + + 1 passing (362ms) + +✨ Done in 3.28s. +``` + +## Contributing + +This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo +containing all resources for developing Neutrino and its core presets. Follow the +[contributing guide](/contributing/README.md) for details. + +[npm-image]: https://badge.fury.io/js/neutrino-preset-jest.svg +[npm-url]: https://npmjs.org/package/neutrino-preset-jest diff --git a/docs/presets/neutrino-preset-mocha/README.md b/docs/presets/neutrino-preset-mocha/README.md index 48a7ad3..b8a6b74 100644 --- a/docs/presets/neutrino-preset-mocha/README.md +++ b/docs/presets/neutrino-preset-mocha/README.md @@ -1 +1,166 @@ -# heading +# Neutrino Mocha Preset [![NPM version][npm-image]][npm-url] + +`neutrino-preset-mocha` is a Neutrino preset that supports testing JavaScript projects with the Mocha test runner. + +## Features + +- Zero upfront configuration necessary to start testing +- Babel compilation that compiles your tests using the same Babel options used by your source code +- Easily extensible to customize your testing as needed + +## Requirements + +- Node.js v6.9+ +- Yarn or npm client +- Neutrino v4, Neutrino build preset + +## Installation + +`neutrino-preset-mocha` can be installed via the Yarn or npm clients. Inside your project, make sure +`neutrino` and `neutrino-preset-mocha` are development dependencies. You will also be using +another Neutrino preset for building your application source code. + +#### Yarn + +```bash +❯ yarn add --dev neutrino-preset-mocha +``` + +#### npm + +```bash +❯ npm install --save-dev neutrino-preset-mocha +``` + +## Project Layout + +`neutrino-preset-mocha` follows the standard [project layout](/project-layout.md) specified by Neutrino. This +means that by default all project test code should live in a directory named `test` in the root of the +project. Test files end in `_test.js` by default. + +## Quickstart + +After adding the Mocha preset to your Neutrino-built project, add a new directory named `test` in the root of the +project, with a single JS file named `simple_test.js` in it. + +```bash +❯ mkdir test && touch test/simple_test.js +``` + +Edit your `test/simple_test.js` file with the following: + +```js +import assert from 'assert'; + +describe('simple', () => { + it('should be sane', () => { + assert.equal(true, !false); + }); +}); +``` + +Now edit your project's package.json to add commands for testing your application. In this example, +let's pretend this is a Node.js project: + +```json +{ + "scripts": { + "test": "neutrino test --presets neutrino-preset-node neutrino-preset-mocha" + } +} +``` + +Run the tests, and view the results in your console: + +#### Yarn + +```bash +❯ yarn test + + simple + ✓ should be sane + + + 1 passing (426ms) + +✨ Done in 4.17s. +``` + +#### npm + +```bash +❯ npm test + + simple + ✓ should be sane + + + 1 passing (409ms) +``` + +To run tests against files from your source code, simply import them: + +```js +import thingToTest from '../src/thing'; +``` + +## Executing single tests + +By default this preset will execute every test file located in your test directory ending in `_test.js`. +Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests. + +## Customizing + +To override the test configuration, start with the documentation on [customization](/customization/README.md). +`neutrino-preset-mocha` creates some conventions to make overriding the configuration easier once you are ready to make +changes. + +### Rules + +The following is a list of rules and their identifiers which can be overridden: + +- `compile`: Compiles JS files from the `test` directory using Babel. Contains a single loader named `babel`. + +### Simple customization + +By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above, +you can override and augment the build directly from package.json. + +### Advanced configuration + +By following the [customization guide](/customization/advanced.md) and knowing the rule, and loader IDs above, +you can override and augment testing by creating a JS module which overrides the config. + +You can modify Mocha settings by overriding the preset with any options Mocha accepts. This is stored in the +`neutrino.custom.mocha` object. + +_Example: Switch the test reporter from the default `spec` to `nyan`:_ + +```js +module.exports = neutrino => { + neutrino.custom.mocha.reporter = 'nyan'; +}; +``` + +```bash +❯ yarn test +yarn test v0.19.1 +$ node_modules/neutrino/bin/neutrino test + 1 -__,------, + 0 -__| /\_/\ + 0 -_~|_( ^ .^) + -_ "" "" + + 1 passing (362ms) + +✨ Done in 3.28s. +``` + +## Contributing + +This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo +containing all resources for developing Neutrino and its core presets. Follow the +[contributing guide](/contributing/README.md) for details. + +[npm-image]: https://badge.fury.io/js/neutrino-preset-mocha.svg +[npm-url]: https://npmjs.org/package/neutrino-preset-mocha diff --git a/docs/presets/neutrino-preset-node/README.md b/docs/presets/neutrino-preset-node/README.md index 4519e8b..deefa0a 100644 --- a/docs/presets/neutrino-preset-node/README.md +++ b/docs/presets/neutrino-preset-node/README.md @@ -1,5 +1,215 @@ -# heading +# Neutrino Node.js Preset [![NPM version][npm-image]][npm-url] + +`neutrino-preset-node` is a Neutrino preset that supports building Node.js applications. + +## Features + +- Zero upfront configuration necessary to start developing and building a Node.js project +- Modern Babel compilation supporting ES modules, Node.js 6.9+, and async functions +- Auto-wired sourcemaps +- Chunking of external dependencies apart from application code +- Easily extensible to customize your project as needed + +## Requirements + +- Node.js v6.9+ +- Yarn or npm client +- Neutrino v4 + +## Installation + +`neutrino-preset-node` can be installed via the Yarn or npm clients. Inside your project, make sure +`neutrino` and `neutrino-preset-node` are development dependencies. + +#### Yarn + +```bash +❯ yarn add --dev neutrino neutrino-preset-node +``` + +#### npm + +```bash +❯ npm install --save-dev neutrino neutrino-preset-node +``` + +## Project Layout + +`neutrino-preset-node` follows the standard [project layout](/project-layout.md) specified by Neutrino. This +means that by default all project source code should live in a directory named `src` in the root of the +project. This includes JavaScript files that would be available to your compiled project. + +## Quickstart + +After installing Neutrino and the Node.js preset, add a new directory named `src` in the root of the project, with +a single JS file named `index.js` in it. + +```bash +❯ mkdir src && touch src/index.js +``` + +Edit your `src/index.js` file with the following: + +```js +import { createServer } from 'http'; + +const delay = ms => new Promise(resolve => setTimeout(resolve, ms)); +const port = process.env.PORT || 3000; + +createServer(async (req, res) => { + await delay(500); + console.log('Request!'); + res.end('hi!'); +}) +.listen(port, () => console.log(`Server running on port ${port}`)); +``` + +Now edit your project's package.json to add commands for starting and building the application. **Important Note:** At the time of writing, Neutrino's Node preset does not support `watch` compilation with `neutrino start`; it will instead fall back to running a build with the `NODE_ENV` environment variable set to `development`. + +```json +{ + "scripts": { + "start": "neutrino start --presets neutrino-preset-node && node build/index.js", + "build": "neutrino build --presets neutrino-preset-node" + } +} +``` + +Start the app, then either open a browser to http://localhost:3000 or use curl from another terminal window: + +#### Yarn + +```bash +❯ yarn start +Warning: This preset does not support watch compilation. Falling back to a one-time build. +Hash: 89e4fb250fc535920ba4 +Version: webpack 2.2.1 +Time: 432ms + Asset Size Chunks Chunk Names + index.js 4.29 kB 0 [emitted] index +index.js.map 3.73 kB 0 [emitted] index +Server running on port 3000 +``` + +```bash +❯ curl http://localhost:3000 +hi! +``` + +#### npm + +```bash +❯ npm start +Warning: This preset does not support watch compilation. Falling back to a one-time build. +Hash: 89e4fb250fc535920ba4 +Version: webpack 2.2.1 +Time: 432ms + Asset Size Chunks Chunk Names + index.js 4.29 kB 0 [emitted] index +index.js.map 3.73 kB 0 [emitted] index +Server running on port 3000 +``` + +```bash +❯ curl http://localhost:3000 +hi! +``` + +## Building + +`neutrino-preset-node` builds assets to the `build` directory by default when running `neutrino build`. Using the +quick start example above as a reference: + +```bash +❯ yarn build +clean-webpack-plugin: /node/build has been removed. +Build completed in 0.419s + +Hash: 89e4fb250fc535920ba4 +Version: webpack 2.2.1 +Time: 424ms + Asset Size Chunks Chunk Names + index.js 4.29 kB 0 [emitted] index +index.js.map 3.73 kB 0 [emitted] index +✨ Done in 1.51s. +``` + +You can either serve or deploy the contents of this `build` directory as a Node.js module, server, or tool. + +## Customizing + +To override the build configuration, start with the documentation on [customization](/customization/README.md). +`neutrino-preset-node` creates some conventions to make overriding the configuration easier once you are ready to make +changes. + +By default the Node.js preset creates a single **main** `index` entry point to your application, and this maps to the +`index.js` file in the `src` directory. This means that the Node.js preset is optimized toward a main entry to your app. +Code not imported in the hierarchy of the `index` entry will not be output to the bundle. To overcome this you +must either define more entry points, or import the code path somewhere along the `index` hierarchy. + +### Vendoring + +This preset automatically vendors all external dependencies into a separate chunk based on their inclusion in your +package.json. No extra work is required to make this work. + +### Rules + +The following is a list of rules and their identifiers which can be overridden: + +- `compile`: Compiles JS files from the `src` directory using Babel. Contains a single loader named `babel`. + +### Plugins + +The following is a list of plugins and their identifiers which can be overridden: + +- `banner`: Injects source-map-support into the entry point of your application. +- `copy`: Copies non-JS files from `src` to `build` when using `neutrino build`. +- `clean`: Clears the contents of `build` prior to creating a production bundle. +- `progress`: Displays a progress bar when using `neutrino build`. + +### Simple customization + +By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above, +you can override and augment the build directly from package.json. + +_Example: Allow importing modules with an `.mjs` extension._ + +```json +{ + "config": { + "neutrino": { + "resolve": { + "extensions": [ + ".mjs" + ] + } + } + } +} +``` + +### Advanced configuration + +By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs above, +you can override and augment the build by creating a JS module which overrides the config. + +_Example: Allow importing modules with an `.mjs` extension._ + +```js +module.exports = neutrino => { + neutrino.config.resolve.extensions.add('.mjs'); +}; +``` + +## Contributing + +This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo +containing all resources for developing Neutrino and its core presets. Follow the +[contributing guide](/contributing/README.md) for details. + +[npm-image]: https://badge.fury.io/js/neutrino-preset-node.svg +[npm-url]: https://npmjs.org/package/neutrino-preset-node diff --git a/docs/presets/neutrino-preset-react/README.md b/docs/presets/neutrino-preset-react/README.md index 6be030f..5966b7c 100644 --- a/docs/presets/neutrino-preset-react/README.md +++ b/docs/presets/neutrino-preset-react/README.md @@ -4,6 +4,7 @@ ## Features +- Zero upfront configuration necessary to start developing and building a React web app - Modern Babel compilation adding JSX and object rest spread syntax. - Support for React Hot Loader - Write JSX in .js or .jsx files @@ -214,6 +215,10 @@ module.exports = neutrino => { }; ``` +## Hot Reloading + + + ## Contributing This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo diff --git a/docs/presets/neutrino-preset-web/README.md b/docs/presets/neutrino-preset-web/README.md index 6ea3349..332e953 100644 --- a/docs/presets/neutrino-preset-web/README.md +++ b/docs/presets/neutrino-preset-web/README.md @@ -4,6 +4,7 @@ ## Features +- Zero upfront configuration necessary to start developing and building a web app - Modern Babel compilation supporting ES modules, last 2 major browser versions, and async functions - Webpack loaders for importing HTML, CSS, images, icons, and fonts - Webpack Dev Server during development