diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a64c61..3aca2e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,14 +2,14 @@ ### So, you want to contribute to Neutrino? -Thank you for wanting to help out with Neutrino! We are very happy that you want to contribute and have put together -this guide to help you get started. We want to do our best to help you make successful contribution and be part of our -team. +Thank you for wanting to help out with Neutrino! We are very happy that you want to contribute, and have put together +this guide to help you get started. We want to do our best to help you make successful contributions and be part of our +community. ### Participation Conduct In order to ensure everyone has a fair, pleasant, and inclusive experience contributing to Neutrino, we ask that you -abide by our [community participation guidelines](CODE_OF_CONDUCT.md), based on the +abide by our [community participation guidelines](/contributing/code-of-conduct.md), based on the [Contributor Covenant](http://contributor-covenant.org/). Please read and understand it for everyone's benefit. Following these guidelines helps to communicate that you respect the time of the developers managing @@ -60,10 +60,10 @@ possible. ## Getting started -Most contributions will involve working with the neutrino-dev codebase. Please refer to the development -documentation for technical details on getting started. +Most contributions will involve working with the neutrino-dev codebase. Please refer to the [development +documentation](/contributing/development.md) for technical details on getting started. -### Tell your contributors how to file a bug report. +## Filing bugs and issues When filing an issue, try to answer these questions: diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 415e8b1..4ce206d 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -15,9 +15,9 @@ * [Customization](/customization/README.md) * [Simple](/customization/simple.md) * [Advanced](/customization/advanced.md) -* [Creating presets](/presets/creating-presets.md) +* [Creating presets](/creating-presets.md) * [API](/api/README.md) * [CLI](/cli/README.md) * [Contributing](/contributing/README.md) - * [Code of Conduct](/contributing/code-of-conduct.md) * [Development Process](/contributing/development.md) + * [Code of Conduct](/contributing/code-of-conduct.md) diff --git a/docs/api/README.md b/docs/api/README.md index fc8ff3c..45c5af7 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,6 +1,6 @@ # Neutrino API -When using Neutrino via the [CLI](/cli), it creates an instance of the Neutrino API which picks up +When using Neutrino via the [CLI](/cli/README.md), it creates an instance of the Neutrino API which picks up any presets and arguments passed on the command line. If you desire, you can also create your own instance of the Neutrino API and interact with it programmatically. @@ -148,9 +148,22 @@ api .then(() => console.log('All custom-events have resolved!')); ``` +By passing an additional argument for `payload`, you can pass custom data to all the event handlers + +```js +api.emitForAll('custom-event', { custom: 'payload' }); + +// ... + +neutrino.on('custom-event', (args, payload) => { + console.log(payload.custom); // "payload" +}); + +``` + ### `handleErrors(err, stats)` -This method is used primarily internally to create a consistent console output when errors occur in the build. It will +This method is used internally to create a consistent console output when errors occur in the build. It will log the `err` property and any errors from `stats` if applicable, and return `true` or `false` depending on if there _were_ errors. @@ -167,7 +180,7 @@ if (failed) { ### `_devServer` This method is used internally to generate an instance of webpack-dev-server during `start()`. It returns a promise that -resolves when the process received a `SIGINT` event to stop. +resolves when the process receives a `SIGINT` event to stop. ```js api diff --git a/docs/contributing/README.md b/docs/contributing/README.md index 16a485e..3aca2e8 100644 --- a/docs/contributing/README.md +++ b/docs/contributing/README.md @@ -2,14 +2,14 @@ ### So, you want to contribute to Neutrino? -Thank you for wanting to help out with Neutrino! We are very happy that you want to contribute and have put together -this guide to help you get started. We want to do our best to help you make successful contribution and be part of our -team. +Thank you for wanting to help out with Neutrino! We are very happy that you want to contribute, and have put together +this guide to help you get started. We want to do our best to help you make successful contributions and be part of our +community. ### Participation Conduct In order to ensure everyone has a fair, pleasant, and inclusive experience contributing to Neutrino, we ask that you -abide by our [community participation guidelines](CODE_OF_CONDUCT.md), based on the +abide by our [community participation guidelines](/contributing/code-of-conduct.md), based on the [Contributor Covenant](http://contributor-covenant.org/). Please read and understand it for everyone's benefit. Following these guidelines helps to communicate that you respect the time of the developers managing diff --git a/docs/contributing/development.md b/docs/contributing/development.md index 2d69b7f..dc8dc49 100644 --- a/docs/contributing/development.md +++ b/docs/contributing/development.md @@ -163,7 +163,7 @@ as possible, following our detailed [contribution guidelines](/contributing/READ ### Congrats! -You just made a contribution to Neutrino! We are so happy to have your help! :tada: +You just made a contribution to Neutrino! We are so happy to have your help! 🎉 ## Receiving updates diff --git a/docs/creating-presets.md b/docs/creating-presets.md index 654b40a..dca6190 100644 --- a/docs/creating-presets.md +++ b/docs/creating-presets.md @@ -137,17 +137,23 @@ module.exports = neutrino => { }; ``` -## Important Points +## Working with paths -- When working with paths, remember that your preset will be running in the context of a project. You should take care +When working with paths, remember that your preset will be running in the context of a project. You should take care to define application paths by referencing the current working directory with `process.cwd()`. For example if you -wanted to work with the project's "src" directory, you would merge the path via `path.join(process.cwd(), 'src)`. -- Because of package conflicts or unknown organization of a project's `node_modules` directory, it is usually safer to +wanted to work with the project's "src" directory, you would merge the path via `path.join(process.cwd(), 'src')` + +## Loader and Babel modules + +Because of package conflicts or unknown layout of a project's `node_modules` directory, it is usually safer to define loaders, Babel plugins, and Babel presets to Webpack absolutely than by name. In our sample preset above, while we could have passed the loader as just `'standard-loader'`, it is safer to resolve its location relative to our preset than having Webpack et al to attempt to load it later from a different, potentially incorrect location. Instead we passed `require.resolve('standard-loader')`. +As a rule of thumb, if your preset is the one using `require`, you are safe to require by name. If you are passing the +name of the module off to be required by Webpack or Babel, instead pass the path to the module via `require.resolve`. + ## Publishing When your preset is ready to be used by others, feel free to publish and distribute! By putting your preset on npm, diff --git a/docs/presets/neutrino-preset-mocha/README.md b/docs/presets/neutrino-preset-mocha/README.md index 2196ea5..3a215a2 100644 --- a/docs/presets/neutrino-preset-mocha/README.md +++ b/docs/presets/neutrino-preset-mocha/README.md @@ -146,8 +146,7 @@ module.exports = neutrino => { ```bash ❯ yarn test -yarn test v0.19.1 -$ node_modules/neutrino/bin/neutrino test + 1 -__,------, 0 -__| /\_/\ 0 -_~|_( ^ .^) diff --git a/docs/presets/neutrino-preset-node/README.md b/docs/presets/neutrino-preset-node/README.md index deefa0a..f237fee 100644 --- a/docs/presets/neutrino-preset-node/README.md +++ b/docs/presets/neutrino-preset-node/README.md @@ -138,7 +138,19 @@ 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. +You can either serve or deploy the contents of this `build` directory as a Node.js module, server, or tool. For Node.js +this usually means adding a `main` property to package.json pointing to the built entry point. Also when publishing your +project to npm, consider excluding your `src` directory by using the `files` property to whitelist `build`, +or via `.npmignore` to blacklist `src`. + +```json +{ + "main": "build/index.js", + "files": [ + "build" + ] +} +``` ## Customizing