diff --git a/README.md b/README.md index 6fddc62..d9ef54d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

### Create and build modern JavaScript applications with zero initial configuration #### Think: Webpack, but with presets. That's Neutrino. diff --git a/docs/README.md b/docs/README.md index 88ed7cf..263c180 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -

+

### Create and build modern JavaScript applications with zero initial configuration #### Think Webpack, but with presets. That's Neutrino. diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 587f913..2d69b7f 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -7,6 +7,14 @@ packages and documentation. _Note: In this guide, commands executable from the command line are prepended with `❯`. Lines not starting with this symbol show sample console output from running the previous command._ +## Requirements + +Developing for neutrino-dev requires: + +- Node.js v6.9+ +- Yarn client, installation instructions at https://yarnpkg.com/en/docs/install +- git, GitHub account + ## Getting started The first step to start developing neutrino-dev is forking the repository to your own GitHub account. @@ -21,6 +29,108 @@ of the account you forked the repository to: ❯ cd neutrino-dev ``` +Upon cloning, you should install dependencies and bootstrap the project: + +```bash +❯ yarn +❯ yarn bootstrap +``` + +This will create symlinks between the various packages, making local development much easier. It also creates yarn links +for testing out these packages elsewhere on your system. + +## Development commands + +The package.json for neutrino-dev defines several commands to assist in the development and deployment process. + +--- + +`bootstrap` + +Installs all sub-package dependencies using yarn. External dependencies are installed normally, whereas those belonging +to the neutrino-dev monorepo itself are `yarn link`ed. + +```bash +❯ yarn bootstrap +``` + +--- + +`deps:add [--dev] <...dependencies>` + +Adds one or more new dependencies or development dependencies to a sub-package. Any flags used, such as `--dev` are +passed on to `yarn add`. For example, if you wanted to add "lodash.clonedeep" to the neutrino package: + +```bash +❯ yarn deps:add neutrino lodash.clonedeep +``` + +--- + +`deps:remove <...dependencies>` + +Removes one or more dependencies from a sub-package. Any flags used are +passed on to `yarn remove`. For example, if you wanted to remove "lodash.clonedeep" from the neutrino package: + +```bash +❯ yarn deps:remove neutrino lodash.clonedeep +``` + +--- + +`deps:upgrade <...dependencies>` + +Upgrades one or more dependencies in a sub-package. Any flags used are +passed on to `yarn upgrade`. For example, if you wanted to upgrade "lodash.clonedeep" in the neutrino package: + +```bash +❯ yarn deps:upgrade neutrino lodash.clonedeep +``` + +--- + +`deps:clean` + +Removes the `node_modules` directory from all sub-packages. After running this you will need to re-bootstrap +neutrino-dev in order to continue development. Useful if you have somehow put your local development environment in an +unworkable state with regards to local inter-dependencies. + +```bash +❯ yarn deps:clean +``` + +--- + +`docs:serve` + +Starts a local development server which builds the documentation in `docs` to a gitbook running on port 4000. + +```bash +❯ yarn docs:serve +``` + +--- + +`docs:build` + +Generates a static site by building the documentation in `docs` to a gitbook to the `_book` directory. + +```bash +❯ yarn docs:build +``` + +--- + +`docs:deploy` + +Generates a static site by building the documentation in `docs` to a gitbook to the `_book` directory, then pushing the +contents of `_book` to a `gh-pages` branch on GitHub. In order to run this command, you must have an `upstream` remote +configured pointing to the root neutrino-dev repo, and have sufficient rights to push to the repository. + +```bash +❯ yarn docs:deploy +``` + ## Making changes When you make changes to neutrino-dev, you should make them in a branch separate from `master`. Start from the @@ -51,6 +161,10 @@ Now if you open the GitHub page for your repository, GitHub should display a but the branch and commit you just pushed. When filling out the details of the pull request, try to be as descriptive as possible, following our detailed [contribution guidelines](/contributing/README.md). +### Congrats! + +You just made a contribution to Neutrino! We are so happy to have your help! :tada: + ## Receiving updates If you need to update your local copy of neutrino-dev to be in sync with the main neutrino-dev repository, you @@ -62,7 +176,3 @@ the latest changes from the master branch. ❯ git remote add upstream https://github.com/mozilla-neutrino/neutrino-dev.git ❯ git pull upstream master ``` - -## Congrats! - -You just made a contribution to Neutrino! We are so happy to have your help! :tada: diff --git a/docs/presets/neutrino-preset-jest/README.md b/docs/presets/neutrino-preset-jest/README.md index ac0413c..221b5db 100644 --- a/docs/presets/neutrino-preset-jest/README.md +++ b/docs/presets/neutrino-preset-jest/README.md @@ -82,9 +82,9 @@ Run the tests, and view the results in your console: Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total -Time: 1.973s +Time: 0.936s Ran all test suites. -✨ Done in 4.43s. +✨ Done in 2.12s. ``` #### npm @@ -99,7 +99,7 @@ Ran all test suites. Test Suites: 1 passed, 1 total Tests: 1 passed, 1 total Snapshots: 0 total -Time: 1.075s +Time: 0.972s Ran all test suites. ``` diff --git a/docs/presets/neutrino-preset-karma/README.md b/docs/presets/neutrino-preset-karma/README.md index 48a7ad3..773dd8d 100644 --- a/docs/presets/neutrino-preset-karma/README.md +++ b/docs/presets/neutrino-preset-karma/README.md @@ -1 +1,188 @@ -# heading +# Neutrino Karma Preset [![NPM version][npm-image]][npm-url] + +`neutrino-preset-karma` is a Neutrino preset that supports testing web applications using the Karma test runner. + +## Features + +- Zero upfront configuration necessary to start testing on real browsers with Karma, Mocha, and Chrome +- Babel compilation that compiles your tests using the same Babel options used by your source code +- Source watching for re-running of tests on change +- Out-of-the-box support for running in CI +- 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-karma` can be installed via the Yarn or npm clients. Inside your project, make sure +`neutrino` and `neutrino-preset-karma` are development dependencies. You will also be using +another Neutrino preset for building your application source code. + +#### Yarn + +```bash +❯ yarn add --dev neutrino-preset-karma +``` + +#### npm + +```bash +❯ npm install --save-dev neutrino-preset-karma +``` + +## Project Layout + +`neutrino-preset-karma` 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 Karma 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 React project: + +```json +{ + "scripts": { + "test": "neutrino test --presets neutrino-preset-node neutrino-preset-karma" + } +} +``` + +Run the tests, and view the results in your console: + +#### Yarn + +```bash +❯ yarn test + +START: +16 02 2017 10:36:34.713:INFO [karma]: Karma v1.4.1 server started at http://0.0.0.0:9876/ +16 02 2017 10:36:34.715:INFO [launcher]: Launching browser Chrome with unlimited concurrency +16 02 2017 10:36:34.731:INFO [launcher]: Starting browser Chrome +16 02 2017 10:36:35.655:INFO [Chrome 56.0.2924 (Mac OS X 10.12.3)]: Connected on socket MkTbqJLpAAa2HFaeAAAA with id 21326158 + simple + ✔ should be sane + +Finished in 0.003 secs / 0 secs @ 10:36:35 GMT-0600 (CST) + +SUMMARY: +✔ 1 test completed +✨ Done in 7.54s. +``` + +#### npm + +```bash +❯ npm test + +START: +16 02 2017 10:38:12.865:INFO [karma]: Karma v1.4.1 server started at http://0.0.0.0:9876/ +16 02 2017 10:38:12.867:INFO [launcher]: Launching browser Chrome with unlimited concurrency +16 02 2017 10:38:12.879:INFO [launcher]: Starting browser Chrome +16 02 2017 10:38:13.688:INFO [Chrome 56.0.2924 (Mac OS X 10.12.3)]: Connected on socket svRGoxU0etKTKQWhAAAA with id 68456725 + simple + ✔ should be sane + +Finished in 0.006 secs / 0 secs @ 10:38:13 GMT-0600 (CST) + +SUMMARY: +✔ 1 test completed +``` + +To run tests against files from your source code, simply import them: + +```js +import thingToTest from '../src/thing'; +``` + +For more details on specific Karma usage, please refer to their +[documentation](https://karma-runner.github.io/1.0/index.html). + +## Executing single tests + +By default this preset will execute every test file located in your test directory ending in the appropriate file +extension. +Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests. + +## Watching for changes + +`neutrino-preset-karma` can watch for changes on your source directory and subsequently re-run tests. Simply use the +`--watch` flag with your `neutrino test` command. + +## Using from CI + +`neutrino-preset-karma` needs no additional configuration to run your tests in CI infrastructure, but you will still +need to ensure your CI can actually run the tests. This usually means having a display emulator and access to the +browsers you are testing against. + +To do this in Travis-CI, you will need to add the following to your `.travis.yml` file for Chrome tests: + +```yaml +before_install: + - export CHROME_BIN=chromium-browser + - export DISPLAY=:99.0 + - sh -e /etc/init.d/xvfb start +``` + +## Customizing + +To override the test configuration, start with the documentation on [customization](/customization/README.md). +`neutrino-preset-karma` creates some conventions to make overriding the configuration easier once you are ready to make +changes. + +### Simple customization + +It is not currently possible to override `neutrino-preset-karma` settings from the package.json using simple +customization. Please use the advanced configuration for changes. + +### Advanced configuration + +By following the [customization guide](/customization/advanced.md) you can override and augment testing by creating a +JS module which overrides the config. + +You can also modify Karma settings by overriding with any options Karma accepts. In a standalone Karma project this is +typically done in a `karma.conf.js` file, but `neutrino-preset-karma` unifies advanced configuration through a preset +override module. When needing to make changes to Karma-specific settings, this is stored in the `neutrino.custom.karma` +object, and takes the same configuration options as outlined in the +[Karma documentation](https://karma-runner.github.io/1.0/config/configuration-file.html). + +_Example: Change the duration Karma waits for a browser to reconnect (in ms)._ + +```js +module.exports = neutrino => { + neutrino.custom.karma.browserDisconnectTimeout = 5000; +}; +``` + +## 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-karma.svg +[npm-url]: https://npmjs.org/package/neutrino-preset-karma diff --git a/docs/presets/neutrino-preset-react/README.md b/docs/presets/neutrino-preset-react/README.md index 5966b7c..d4ccbc4 100644 --- a/docs/presets/neutrino-preset-react/README.md +++ b/docs/presets/neutrino-preset-react/README.md @@ -217,7 +217,50 @@ module.exports = neutrino => { ## Hot Reloading +While `neutrino-preset-react` supports hot reloading your app using React Hot Loader, it does require some +application-specific changes in order to operate. +First, install `react-hot-loader` as a dependency, this **must** be React Hot Loader v3+ (currently in beta): + +#### Yarn + +```bash +❯ yarn add react-hot-loader@next +``` + +#### npm + +```bash +❯ npm install --save react-hot-loader@next +``` + +--- + +- From your `index` entry point (`src/index.js`), import an `AppContainer` from `react-hot-loader`. +- Wrap your top-level React component in the `AppContainer`. +- Perform the application render in a reusable function for initial load and subsequent reloads. +- Add the `hot` acceptance to call this function. + +For example: + +```jsx +import React from 'react'; +import { render } from 'react-dom'; +import { AppContainer } from 'react-hot-loader'; +import MyApp from './MyApp'; + +const load = () => render(( + + + +), document.getElementById('root')); + +if (module.hot) { + module.hot.accept('./MyApp', load); +} + +load(); +``` ## Contributing diff --git a/package.json b/package.json index ec9a5d6..9db35e7 100644 --- a/package.json +++ b/package.json @@ -13,8 +13,8 @@ "deps:remove": "oao remove", "deps:upgrade": "oao upgrade", "deps:clean": "rm -rf packages/**/node_modules", - "docs:build": "gitbook build", - "docs:deploy": "npm run docs:build && cp CNAME _book && gh-pages --dist _book --remote upstream", + "docs:build": "gitbook build && cp CNAME _book", + "docs:deploy": "yarn docs:build && gh-pages --dist _book --remote upstream", "docs:serve": "gitbook serve" }, "devDependencies": { diff --git a/packages/neutrino-preset-airbnb-base/README.md b/packages/neutrino-preset-airbnb-base/README.md index 9c1ea4a..12088c3 100644 --- a/packages/neutrino-preset-airbnb-base/README.md +++ b/packages/neutrino-preset-airbnb-base/README.md @@ -5,7 +5,7 @@ config, following the [Airbnb styleguide](https://github.com/airbnb/javascript). ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-airbnb-base/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-airbnb-base/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-airbnb-base.svg diff --git a/packages/neutrino-preset-jest/README.md b/packages/neutrino-preset-jest/README.md index 40b4e2f..b486855 100644 --- a/packages/neutrino-preset-jest/README.md +++ b/packages/neutrino-preset-jest/README.md @@ -4,7 +4,7 @@ ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-jest/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-jest/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-jest.svg diff --git a/packages/neutrino-preset-karma/README.md b/packages/neutrino-preset-karma/README.md index 6c5d3d6..214614a 100644 --- a/packages/neutrino-preset-karma/README.md +++ b/packages/neutrino-preset-karma/README.md @@ -4,7 +4,7 @@ ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-karma/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-karma/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-karma.svg diff --git a/packages/neutrino-preset-mocha/README.md b/packages/neutrino-preset-mocha/README.md index 10aef4b..c18176e 100644 --- a/packages/neutrino-preset-mocha/README.md +++ b/packages/neutrino-preset-mocha/README.md @@ -4,7 +4,7 @@ ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-mocha/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-mocha/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-mocha.svg diff --git a/packages/neutrino-preset-node/README.md b/packages/neutrino-preset-node/README.md index b5b3dd7..ff34529 100644 --- a/packages/neutrino-preset-node/README.md +++ b/packages/neutrino-preset-node/README.md @@ -4,7 +4,7 @@ ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-node/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-node/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-node.svg diff --git a/packages/neutrino-preset-react/README.md b/packages/neutrino-preset-react/README.md index a91c4af..c9db49c 100644 --- a/packages/neutrino-preset-react/README.md +++ b/packages/neutrino-preset-react/README.md @@ -4,7 +4,7 @@ ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-react/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-react/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-react.svg diff --git a/packages/neutrino-preset-web/README.md b/packages/neutrino-preset-web/README.md index bf13936..6c86189 100644 --- a/packages/neutrino-preset-web/README.md +++ b/packages/neutrino-preset-web/README.md @@ -4,7 +4,7 @@ ## Documentation -See the [Neutrino docs](http://neutrino.js.org/presets/neutrino-preset-web/) +See the [Neutrino docs](https://neutrino.js.org/presets/neutrino-preset-web/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino-preset-web.svg diff --git a/packages/neutrino/README.md b/packages/neutrino/README.md index 94070cd..137600a 100644 --- a/packages/neutrino/README.md +++ b/packages/neutrino/README.md @@ -1,4 +1,4 @@ -

+

### Create and build modern JavaScript applications with zero initial configuration #### Think Webpack, but with presets. That's Neutrino. @@ -19,7 +19,7 @@ cover. ## Documentation -See the [Neutrino docs](http://neutrino.js.org/) +See the [Neutrino docs](https://neutrino.js.org/) for details on installation, getting started, usage, and customizing. [npm-image]: https://badge.fury.io/js/neutrino.svg