Eli Perelman
8 years ago
committed by
GitHub
GitHub
36 changed files with 3359 additions and 493 deletions
@ -0,0 +1,74 @@ |
|||
# Contributor Covenant Code of Conduct |
|||
|
|||
## Our Pledge |
|||
|
|||
In the interest of fostering an open and welcoming environment, we as |
|||
contributors and maintainers pledge to making participation in our project and |
|||
our community a harassment-free experience for everyone, regardless of age, body |
|||
size, disability, ethnicity, gender identity and expression, level of experience, |
|||
nationality, personal appearance, race, religion, or sexual identity and |
|||
orientation. |
|||
|
|||
## Our Standards |
|||
|
|||
Examples of behavior that contributes to creating a positive environment |
|||
include: |
|||
|
|||
* Using welcoming and inclusive language |
|||
* Being respectful of differing viewpoints and experiences |
|||
* Gracefully accepting constructive criticism |
|||
* Focusing on what is best for the community |
|||
* Showing empathy towards other community members |
|||
|
|||
Examples of unacceptable behavior by participants include: |
|||
|
|||
* The use of sexualized language or imagery and unwelcome sexual attention or |
|||
advances |
|||
* Trolling, insulting/derogatory comments, and personal or political attacks |
|||
* Public or private harassment |
|||
* Publishing others' private information, such as a physical or electronic |
|||
address, without explicit permission |
|||
* Other conduct which could reasonably be considered inappropriate in a |
|||
professional setting |
|||
|
|||
## Our Responsibilities |
|||
|
|||
Project maintainers are responsible for clarifying the standards of acceptable |
|||
behavior and are expected to take appropriate and fair corrective action in |
|||
response to any instances of unacceptable behavior. |
|||
|
|||
Project maintainers have the right and responsibility to remove, edit, or |
|||
reject comments, commits, code, wiki edits, issues, and other contributions |
|||
that are not aligned to this Code of Conduct, or to ban temporarily or |
|||
permanently any contributor for other behaviors that they deem inappropriate, |
|||
threatening, offensive, or harmful. |
|||
|
|||
## Scope |
|||
|
|||
This Code of Conduct applies both within project spaces and in public spaces |
|||
when an individual is representing the project or its community. Examples of |
|||
representing a project or community include using an official project e-mail |
|||
address, posting via an official social media account, or acting as an appointed |
|||
representative at an online or offline event. Representation of a project may be |
|||
further defined and clarified by project maintainers. |
|||
|
|||
## Enforcement |
|||
|
|||
Instances of abusive, harassing, or otherwise unacceptable behavior may be |
|||
reported by contacting the project lead at eli@mozilla.com. All |
|||
complaints will be reviewed and investigated and will result in a response that |
|||
is deemed necessary and appropriate to the circumstances. The project team is |
|||
obligated to maintain confidentiality with regard to the reporter of an incident. |
|||
Further details of specific enforcement policies may be posted separately. |
|||
|
|||
Project maintainers who do not follow or enforce the Code of Conduct in good |
|||
faith may face temporary or permanent repercussions as determined by other |
|||
members of the project's leadership. |
|||
|
|||
## Attribution |
|||
|
|||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, |
|||
available at [http://contributor-covenant.org/version/1/4][version] |
|||
|
|||
[homepage]: http://contributor-covenant.org |
|||
[version]: http://contributor-covenant.org/version/1/4/ |
|||
@ -0,0 +1,94 @@ |
|||
# Contributing |
|||
|
|||
### 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 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](/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 |
|||
and developing Neutrino. In return, we will show you respect in addressing your issue, assessing changes, |
|||
and helping you finalize your pull requests. |
|||
|
|||
### What we need |
|||
|
|||
There is always room for improvement and expansion in Neutrino. Some things that could always help: |
|||
|
|||
- Triaging and fixing bugs |
|||
- Adding tests to Neutrino which can help ensure it functions properly with new contributions |
|||
- Keeping core presets up to date with the best Webpack and Babel options |
|||
- Expanding documentation, writing tutorials, and creating example projects |
|||
- Something else, of course! |
|||
|
|||
### What we probably don't need |
|||
|
|||
While we are happy to review **any** contribution, there are some things that are best left as an external project: |
|||
|
|||
- _Additional presets_. While neutrino-dev does contain a number of core presets, we created and maintain these because |
|||
they were core to most of the projects we personally work on. If there are more presets you believe should be maintained |
|||
by the core, then feel free to raise an issue and we can discuss! Most likely though, additional presets can be |
|||
externally maintained and published to npm. It still has the same reach potential as bringing it into the core, without |
|||
raising the maintenance burden for Neutrino unnecessarily. |
|||
- _Scaffolding and boilerplates._ The goal of Neutrino is to remove over-reliance on boilerplates, instead opting to |
|||
push users into consuming presets. Neutrino itself will not add commands to scaffold out new projects or create |
|||
boilerplate repositories. We do keep a collection of examples-as-documentation for getting started with Neutrino |
|||
presets, but do not wish to govern project structure more than necessary. These types of projects can be maintained |
|||
externally. |
|||
|
|||
## Support |
|||
|
|||
Neutrino team members and contributors are here to help you! Should you need assistance or have questions in using |
|||
Neutrino or its core presets, please consider asking on Stack Overflow or other channel rather than filing issues. We |
|||
would prefer to keep our GitHub issues clear for bugs, feature requests, discussions, and relevant information related |
|||
to its development. |
|||
|
|||
## Guidelines |
|||
|
|||
- Please make a good-faith effort to ensure that code that goes into neutrino-dev follows the existing patterns and |
|||
quality that is already present in the repository. |
|||
- Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get |
|||
community feedback. |
|||
- Strive for code to be readable. Prefer following functional programming paradigms over object-oriented ones where |
|||
possible. |
|||
- Keep feature versions as small as possible, preferably one new feature per version. |
|||
|
|||
## 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. |
|||
|
|||
## Filing bugs and issues |
|||
|
|||
When filing an issue, try to answer these questions: |
|||
|
|||
- What version of Neutrino are you using? |
|||
- Are you trying to use any presets? If so, which ones, and what versions? |
|||
- Are you using the Yarn client or the npm client? What version? |
|||
- What version of Node.js are you using? |
|||
- What operating system are you using? |
|||
- What did you do? |
|||
- What did you expect to happen? |
|||
- What actually happened, contrary to your expectations? |
|||
|
|||
## Feature Requests or Enhancements |
|||
|
|||
Please file an issue describing your request in detail: |
|||
|
|||
- What is the goal of the change? |
|||
- What are the pros and cons of the change? |
|||
- Could this dramatically improve the experience of our users? |
|||
|
|||
Please be open to discussion, and we will respect your time by fairly evaluating your request. In the event that your |
|||
request is deemed to not be acceptable to move forward, please understand that isn't a criticism of you as a person, |
|||
but rather that the idea in its present form may not be right at this time. We respect you and your ideas, and will |
|||
always encourage contributors to continue to make proposals. |
|||
|
|||
## Code review process |
|||
|
|||
Code is reviewed by Neutrino team members for quality, conformance to existing patterns, and functionality. |
|||
@ -0,0 +1,373 @@ |
|||
Mozilla Public License Version 2.0 |
|||
================================== |
|||
|
|||
1. Definitions |
|||
-------------- |
|||
|
|||
1.1. "Contributor" |
|||
means each individual or legal entity that creates, contributes to |
|||
the creation of, or owns Covered Software. |
|||
|
|||
1.2. "Contributor Version" |
|||
means the combination of the Contributions of others (if any) used |
|||
by a Contributor and that particular Contributor's Contribution. |
|||
|
|||
1.3. "Contribution" |
|||
means Covered Software of a particular Contributor. |
|||
|
|||
1.4. "Covered Software" |
|||
means Source Code Form to which the initial Contributor has attached |
|||
the notice in Exhibit A, the Executable Form of such Source Code |
|||
Form, and Modifications of such Source Code Form, in each case |
|||
including portions thereof. |
|||
|
|||
1.5. "Incompatible With Secondary Licenses" |
|||
means |
|||
|
|||
(a) that the initial Contributor has attached the notice described |
|||
in Exhibit B to the Covered Software; or |
|||
|
|||
(b) that the Covered Software was made available under the terms of |
|||
version 1.1 or earlier of the License, but not also under the |
|||
terms of a Secondary License. |
|||
|
|||
1.6. "Executable Form" |
|||
means any form of the work other than Source Code Form. |
|||
|
|||
1.7. "Larger Work" |
|||
means a work that combines Covered Software with other material, in |
|||
a separate file or files, that is not Covered Software. |
|||
|
|||
1.8. "License" |
|||
means this document. |
|||
|
|||
1.9. "Licensable" |
|||
means having the right to grant, to the maximum extent possible, |
|||
whether at the time of the initial grant or subsequently, any and |
|||
all of the rights conveyed by this License. |
|||
|
|||
1.10. "Modifications" |
|||
means any of the following: |
|||
|
|||
(a) any file in Source Code Form that results from an addition to, |
|||
deletion from, or modification of the contents of Covered |
|||
Software; or |
|||
|
|||
(b) any new file in Source Code Form that contains any Covered |
|||
Software. |
|||
|
|||
1.11. "Patent Claims" of a Contributor |
|||
means any patent claim(s), including without limitation, method, |
|||
process, and apparatus claims, in any patent Licensable by such |
|||
Contributor that would be infringed, but for the grant of the |
|||
License, by the making, using, selling, offering for sale, having |
|||
made, import, or transfer of either its Contributions or its |
|||
Contributor Version. |
|||
|
|||
1.12. "Secondary License" |
|||
means either the GNU General Public License, Version 2.0, the GNU |
|||
Lesser General Public License, Version 2.1, the GNU Affero General |
|||
Public License, Version 3.0, or any later versions of those |
|||
licenses. |
|||
|
|||
1.13. "Source Code Form" |
|||
means the form of the work preferred for making modifications. |
|||
|
|||
1.14. "You" (or "Your") |
|||
means an individual or a legal entity exercising rights under this |
|||
License. For legal entities, "You" includes any entity that |
|||
controls, is controlled by, or is under common control with You. For |
|||
purposes of this definition, "control" means (a) the power, direct |
|||
or indirect, to cause the direction or management of such entity, |
|||
whether by contract or otherwise, or (b) ownership of more than |
|||
fifty percent (50%) of the outstanding shares or beneficial |
|||
ownership of such entity. |
|||
|
|||
2. License Grants and Conditions |
|||
-------------------------------- |
|||
|
|||
2.1. Grants |
|||
|
|||
Each Contributor hereby grants You a world-wide, royalty-free, |
|||
non-exclusive license: |
|||
|
|||
(a) under intellectual property rights (other than patent or trademark) |
|||
Licensable by such Contributor to use, reproduce, make available, |
|||
modify, display, perform, distribute, and otherwise exploit its |
|||
Contributions, either on an unmodified basis, with Modifications, or |
|||
as part of a Larger Work; and |
|||
|
|||
(b) under Patent Claims of such Contributor to make, use, sell, offer |
|||
for sale, have made, import, and otherwise transfer either its |
|||
Contributions or its Contributor Version. |
|||
|
|||
2.2. Effective Date |
|||
|
|||
The licenses granted in Section 2.1 with respect to any Contribution |
|||
become effective for each Contribution on the date the Contributor first |
|||
distributes such Contribution. |
|||
|
|||
2.3. Limitations on Grant Scope |
|||
|
|||
The licenses granted in this Section 2 are the only rights granted under |
|||
this License. No additional rights or licenses will be implied from the |
|||
distribution or licensing of Covered Software under this License. |
|||
Notwithstanding Section 2.1(b) above, no patent license is granted by a |
|||
Contributor: |
|||
|
|||
(a) for any code that a Contributor has removed from Covered Software; |
|||
or |
|||
|
|||
(b) for infringements caused by: (i) Your and any other third party's |
|||
modifications of Covered Software, or (ii) the combination of its |
|||
Contributions with other software (except as part of its Contributor |
|||
Version); or |
|||
|
|||
(c) under Patent Claims infringed by Covered Software in the absence of |
|||
its Contributions. |
|||
|
|||
This License does not grant any rights in the trademarks, service marks, |
|||
or logos of any Contributor (except as may be necessary to comply with |
|||
the notice requirements in Section 3.4). |
|||
|
|||
2.4. Subsequent Licenses |
|||
|
|||
No Contributor makes additional grants as a result of Your choice to |
|||
distribute the Covered Software under a subsequent version of this |
|||
License (see Section 10.2) or under the terms of a Secondary License (if |
|||
permitted under the terms of Section 3.3). |
|||
|
|||
2.5. Representation |
|||
|
|||
Each Contributor represents that the Contributor believes its |
|||
Contributions are its original creation(s) or it has sufficient rights |
|||
to grant the rights to its Contributions conveyed by this License. |
|||
|
|||
2.6. Fair Use |
|||
|
|||
This License is not intended to limit any rights You have under |
|||
applicable copyright doctrines of fair use, fair dealing, or other |
|||
equivalents. |
|||
|
|||
2.7. Conditions |
|||
|
|||
Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted |
|||
in Section 2.1. |
|||
|
|||
3. Responsibilities |
|||
------------------- |
|||
|
|||
3.1. Distribution of Source Form |
|||
|
|||
All distribution of Covered Software in Source Code Form, including any |
|||
Modifications that You create or to which You contribute, must be under |
|||
the terms of this License. You must inform recipients that the Source |
|||
Code Form of the Covered Software is governed by the terms of this |
|||
License, and how they can obtain a copy of this License. You may not |
|||
attempt to alter or restrict the recipients' rights in the Source Code |
|||
Form. |
|||
|
|||
3.2. Distribution of Executable Form |
|||
|
|||
If You distribute Covered Software in Executable Form then: |
|||
|
|||
(a) such Covered Software must also be made available in Source Code |
|||
Form, as described in Section 3.1, and You must inform recipients of |
|||
the Executable Form how they can obtain a copy of such Source Code |
|||
Form by reasonable means in a timely manner, at a charge no more |
|||
than the cost of distribution to the recipient; and |
|||
|
|||
(b) You may distribute such Executable Form under the terms of this |
|||
License, or sublicense it under different terms, provided that the |
|||
license for the Executable Form does not attempt to limit or alter |
|||
the recipients' rights in the Source Code Form under this License. |
|||
|
|||
3.3. Distribution of a Larger Work |
|||
|
|||
You may create and distribute a Larger Work under terms of Your choice, |
|||
provided that You also comply with the requirements of this License for |
|||
the Covered Software. If the Larger Work is a combination of Covered |
|||
Software with a work governed by one or more Secondary Licenses, and the |
|||
Covered Software is not Incompatible With Secondary Licenses, this |
|||
License permits You to additionally distribute such Covered Software |
|||
under the terms of such Secondary License(s), so that the recipient of |
|||
the Larger Work may, at their option, further distribute the Covered |
|||
Software under the terms of either this License or such Secondary |
|||
License(s). |
|||
|
|||
3.4. Notices |
|||
|
|||
You may not remove or alter the substance of any license notices |
|||
(including copyright notices, patent notices, disclaimers of warranty, |
|||
or limitations of liability) contained within the Source Code Form of |
|||
the Covered Software, except that You may alter any license notices to |
|||
the extent required to remedy known factual inaccuracies. |
|||
|
|||
3.5. Application of Additional Terms |
|||
|
|||
You may choose to offer, and to charge a fee for, warranty, support, |
|||
indemnity or liability obligations to one or more recipients of Covered |
|||
Software. However, You may do so only on Your own behalf, and not on |
|||
behalf of any Contributor. You must make it absolutely clear that any |
|||
such warranty, support, indemnity, or liability obligation is offered by |
|||
You alone, and You hereby agree to indemnify every Contributor for any |
|||
liability incurred by such Contributor as a result of warranty, support, |
|||
indemnity or liability terms You offer. You may include additional |
|||
disclaimers of warranty and limitations of liability specific to any |
|||
jurisdiction. |
|||
|
|||
4. Inability to Comply Due to Statute or Regulation |
|||
--------------------------------------------------- |
|||
|
|||
If it is impossible for You to comply with any of the terms of this |
|||
License with respect to some or all of the Covered Software due to |
|||
statute, judicial order, or regulation then You must: (a) comply with |
|||
the terms of this License to the maximum extent possible; and (b) |
|||
describe the limitations and the code they affect. Such description must |
|||
be placed in a text file included with all distributions of the Covered |
|||
Software under this License. Except to the extent prohibited by statute |
|||
or regulation, such description must be sufficiently detailed for a |
|||
recipient of ordinary skill to be able to understand it. |
|||
|
|||
5. Termination |
|||
-------------- |
|||
|
|||
5.1. The rights granted under this License will terminate automatically |
|||
if You fail to comply with any of its terms. However, if You become |
|||
compliant, then the rights granted under this License from a particular |
|||
Contributor are reinstated (a) provisionally, unless and until such |
|||
Contributor explicitly and finally terminates Your grants, and (b) on an |
|||
ongoing basis, if such Contributor fails to notify You of the |
|||
non-compliance by some reasonable means prior to 60 days after You have |
|||
come back into compliance. Moreover, Your grants from a particular |
|||
Contributor are reinstated on an ongoing basis if such Contributor |
|||
notifies You of the non-compliance by some reasonable means, this is the |
|||
first time You have received notice of non-compliance with this License |
|||
from such Contributor, and You become compliant prior to 30 days after |
|||
Your receipt of the notice. |
|||
|
|||
5.2. If You initiate litigation against any entity by asserting a patent |
|||
infringement claim (excluding declaratory judgment actions, |
|||
counter-claims, and cross-claims) alleging that a Contributor Version |
|||
directly or indirectly infringes any patent, then the rights granted to |
|||
You by any and all Contributors for the Covered Software under Section |
|||
2.1 of this License shall terminate. |
|||
|
|||
5.3. In the event of termination under Sections 5.1 or 5.2 above, all |
|||
end user license agreements (excluding distributors and resellers) which |
|||
have been validly granted by You or Your distributors under this License |
|||
prior to termination shall survive termination. |
|||
|
|||
************************************************************************ |
|||
* * |
|||
* 6. Disclaimer of Warranty * |
|||
* ------------------------- * |
|||
* * |
|||
* Covered Software is provided under this License on an "as is" * |
|||
* basis, without warranty of any kind, either expressed, implied, or * |
|||
* statutory, including, without limitation, warranties that the * |
|||
* Covered Software is free of defects, merchantable, fit for a * |
|||
* particular purpose or non-infringing. The entire risk as to the * |
|||
* quality and performance of the Covered Software is with You. * |
|||
* Should any Covered Software prove defective in any respect, You * |
|||
* (not any Contributor) assume the cost of any necessary servicing, * |
|||
* repair, or correction. This disclaimer of warranty constitutes an * |
|||
* essential part of this License. No use of any Covered Software is * |
|||
* authorized under this License except under this disclaimer. * |
|||
* * |
|||
************************************************************************ |
|||
|
|||
************************************************************************ |
|||
* * |
|||
* 7. Limitation of Liability * |
|||
* -------------------------- * |
|||
* * |
|||
* Under no circumstances and under no legal theory, whether tort * |
|||
* (including negligence), contract, or otherwise, shall any * |
|||
* Contributor, or anyone who distributes Covered Software as * |
|||
* permitted above, be liable to You for any direct, indirect, * |
|||
* special, incidental, or consequential damages of any character * |
|||
* including, without limitation, damages for lost profits, loss of * |
|||
* goodwill, work stoppage, computer failure or malfunction, or any * |
|||
* and all other commercial damages or losses, even if such party * |
|||
* shall have been informed of the possibility of such damages. This * |
|||
* limitation of liability shall not apply to liability for death or * |
|||
* personal injury resulting from such party's negligence to the * |
|||
* extent applicable law prohibits such limitation. Some * |
|||
* jurisdictions do not allow the exclusion or limitation of * |
|||
* incidental or consequential damages, so this exclusion and * |
|||
* limitation may not apply to You. * |
|||
* * |
|||
************************************************************************ |
|||
|
|||
8. Litigation |
|||
------------- |
|||
|
|||
Any litigation relating to this License may be brought only in the |
|||
courts of a jurisdiction where the defendant maintains its principal |
|||
place of business and such litigation shall be governed by laws of that |
|||
jurisdiction, without reference to its conflict-of-law provisions. |
|||
Nothing in this Section shall prevent a party's ability to bring |
|||
cross-claims or counter-claims. |
|||
|
|||
9. Miscellaneous |
|||
---------------- |
|||
|
|||
This License represents the complete agreement concerning the subject |
|||
matter hereof. If any provision of this License is held to be |
|||
unenforceable, such provision shall be reformed only to the extent |
|||
necessary to make it enforceable. Any law or regulation which provides |
|||
that the language of a contract shall be construed against the drafter |
|||
shall not be used to construe this License against a Contributor. |
|||
|
|||
10. Versions of the License |
|||
--------------------------- |
|||
|
|||
10.1. New Versions |
|||
|
|||
Mozilla Foundation is the license steward. Except as provided in Section |
|||
10.3, no one other than the license steward has the right to modify or |
|||
publish new versions of this License. Each version will be given a |
|||
distinguishing version number. |
|||
|
|||
10.2. Effect of New Versions |
|||
|
|||
You may distribute the Covered Software under the terms of the version |
|||
of the License under which You originally received the Covered Software, |
|||
or under the terms of any subsequent version published by the license |
|||
steward. |
|||
|
|||
10.3. Modified Versions |
|||
|
|||
If you create software not governed by this License, and you want to |
|||
create a new license for such software, you may create and use a |
|||
modified version of this License if you rename the license and remove |
|||
any references to the name of the license steward (except to note that |
|||
such modified license differs from this License). |
|||
|
|||
10.4. Distributing Source Code Form that is Incompatible With Secondary |
|||
Licenses |
|||
|
|||
If You choose to distribute Source Code Form that is Incompatible With |
|||
Secondary Licenses under the terms of this version of the License, the |
|||
notice described in Exhibit B of this License must be attached. |
|||
|
|||
Exhibit A - Source Code Form License Notice |
|||
------------------------------------------- |
|||
|
|||
This Source Code Form is subject to the terms of the Mozilla Public |
|||
License, v. 2.0. If a copy of the MPL was not distributed with this |
|||
file, You can obtain one at http://mozilla.org/MPL/2.0/. |
|||
|
|||
If it is not possible or desirable to put the notice in a particular |
|||
file, then You may include the notice in a location (such as a LICENSE |
|||
file in a relevant directory) where a recipient would be likely to look |
|||
for such a notice. |
|||
|
|||
You may add additional accurate notices of copyright ownership. |
|||
|
|||
Exhibit B - "Incompatible With Secondary Licenses" Notice |
|||
--------------------------------------------------------- |
|||
|
|||
This Source Code Form is "Incompatible With Secondary Licenses", as |
|||
defined by the Mozilla Public License, v. 2.0. |
|||
@ -1,11 +1,21 @@ |
|||
<h1><p align="center"><a href="http://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1> |
|||
<h1><p align="center"><a href="https://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1> |
|||
|
|||
### Create and build modern JavaScript applications with zero initial configuration |
|||
#### Think: Webpack, but with presets. That's Neutrino. |
|||
#### Think Webpack, but with presets. That's Neutrino. |
|||
|
|||
[![NPM version][npm-image]][npm-url] |
|||
|
|||
--- |
|||
|
|||
Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. It intends to make the process of initializing and building projects much simpler by providing minimal development dependencies. |
|||
Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. |
|||
It intends to make the process of initializing and building projects much simpler by providing minimal development |
|||
dependencies. |
|||
|
|||
Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared |
|||
across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create |
|||
your own presets by extending the Neutrino core ones to be shared across your own projects or even by the community. |
|||
Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't |
|||
cover. |
|||
|
|||
Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create your |
|||
own presets by extending the Neutrino core ones to be shared across your own projects or even by the community. Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't cover. |
|||
[npm-image]: https://badge.fury.io/js/neutrino.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino |
|||
|
|||
@ -0,0 +1,189 @@ |
|||
# Neutrino API |
|||
|
|||
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. |
|||
|
|||
## Instantiation |
|||
|
|||
In order to access the Neutrino API, you must require or import it and instantiate it, passing in any |
|||
preset names or paths you wish to load: |
|||
|
|||
Using `require`: |
|||
|
|||
```js |
|||
const Neutrino = require('neutrino'); |
|||
const api = new Neutrino(['neutrino-preset-react']); |
|||
``` |
|||
|
|||
Using ES imports: |
|||
|
|||
```js |
|||
import Neutrino from 'neutrino'; |
|||
|
|||
const api = new Neutrino(['neutrino-preset-react']); |
|||
``` |
|||
|
|||
## Environment |
|||
|
|||
When using the CLI, environment variables are automatically set based on the command you are using. |
|||
When using the API this is not the case, and you **must** set it prior to calling any build commands or |
|||
loading any presets. |
|||
|
|||
```js |
|||
process.env.NODE_ENV = 'production'; |
|||
|
|||
const api = new Neutrino(); |
|||
api.build(); |
|||
``` |
|||
|
|||
## API |
|||
|
|||
### Constructor |
|||
|
|||
When creating a Neutrino instance, you have the option of providing an array of presets for the API to attempt |
|||
to load and merge configurations for. Each preset will attempt to be loaded from the current working directory's |
|||
`node_modules`, nested within, by name, or relative file path. If it cannot be found, an exception will be thrown. |
|||
|
|||
In addition to any provided presets, Neutrino will also attempt to load configuration data from the package.json |
|||
residing in the current working directory. If this package.json contains an object at `config.neutrino`, this data |
|||
will be merged. |
|||
|
|||
### `.config` |
|||
|
|||
When constructing a Neutrino instance, a property of `.config` is set to be a new instance of |
|||
[webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). This property is then available to all presets, which |
|||
subsequently augment it with their specific options. Every preset added uses this single `.config` to store their data, |
|||
meaning that preset load order has an effect on which config values take precedence. Presets loaded later will override |
|||
values set by earlier presets. |
|||
|
|||
### `start(args)` |
|||
|
|||
The `start()` method is responsible for creating a development bundle, and when possible, starting a development |
|||
server or source watcher. Prior to starting this process, Neutrino will trigger and wait for `prestart` events to |
|||
finish. After it is complete, Neutrino will trigger and wait for `start` events to finish. |
|||
|
|||
If the Neutrino config contains options for `devServer`, then a webpack-dev-server will be started. If it is |
|||
configured for Node.js, then a build will be created, otherwise a Webpack source watcher will be started. |
|||
|
|||
Currently any `args` passed to `start()` have no effect and will be passed through to any event handlers. |
|||
|
|||
The `start` method will return a Promise which resolves after the build is done or development watcher has stopped, |
|||
and all `start` events have finished. |
|||
|
|||
```js |
|||
api |
|||
.start() |
|||
.then(() => console.log('Exiting!')); |
|||
``` |
|||
|
|||
### `build(args)` |
|||
|
|||
The `build()` method is responsible for creating a bundle typically used for production. Prior to starting this process, |
|||
Neutrino will trigger and wait for `prebuild` events to finish. After it is complete, Neutrino will trigger and wait for |
|||
`build` events to finish. |
|||
|
|||
Currently any `args` passed to `build()` have no effect and will be passed through to any event handlers. |
|||
|
|||
The `build` method will return a Promise which resolves after the build is done and all `build` events have finished, or |
|||
will reject if there was a failure during building. |
|||
|
|||
```js |
|||
api |
|||
.build() |
|||
.then(() => console.log('Saved to build/')) |
|||
.catch(err => console.error(err)); |
|||
``` |
|||
|
|||
### `test(args)` |
|||
|
|||
The `test()` method is responsible for gathering args needed for testing and triggering relevant events as a signal to |
|||
test presets that they may run. Using the `test` method does nothing other than triggering these events; without a |
|||
preset listening for these events, nothing will happen. Prior to starting this process, Neutrino will trigger and wait |
|||
for `pretest` events to finish. After it is complete, Neutrino will trigger and wait for |
|||
`test` events to finish, in which test runners will do their work. |
|||
|
|||
Any `args` passed to `test()` are passed on to the event handles and typically have properties for an array of |
|||
`files` to test, as well as a property for `watch`ing and rerunning tests. |
|||
|
|||
The `test` method will return a Promise which resolves after all `test` events have finished, or |
|||
will reject if there was a failure during testing. |
|||
|
|||
```js |
|||
api |
|||
.test() |
|||
.then(() => console.log('all passed')) |
|||
.catch(err => console.error(err)); |
|||
|
|||
api |
|||
.test({ |
|||
files: [/* ... */], |
|||
watch: true |
|||
}) |
|||
.then(() => console.log('all passed')); |
|||
``` |
|||
|
|||
### `getWebpackOptions()` |
|||
|
|||
While tools like webpack-chain provide a convenient API for creating Webpack configurations, this is not a format that |
|||
is understandable by Webpack. With `getWebpackOptions()`, the webpack-chain instance at `.config` will be converted to |
|||
an options object readable directly by Webpack. This call is cached, so subsequent calls to `getWebpackOptions` will |
|||
result in the config being rendered only once, but the cached value returned afterwards. |
|||
|
|||
```js |
|||
api.getWebpackOptions(); // -> { ... } |
|||
``` |
|||
|
|||
### `emitForAll(eventName, payload)` |
|||
|
|||
Trigger a Promise-dependent event. For example, calling `emitForAll('build')` will trigger an event named build, and |
|||
each event handler can return a Promise denoting when it is finished. When all events have finished, this call will |
|||
resolve. |
|||
|
|||
This method returns a Promise which resolves when all event handlers have also resolved. |
|||
|
|||
```js |
|||
api |
|||
.emitForAll('custom-event') |
|||
.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 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. |
|||
|
|||
This method returns a Boolean. |
|||
|
|||
```js |
|||
const failed = api.handleErrors(err, stats); |
|||
|
|||
if (failed) { |
|||
console.log('The build 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 receives a `SIGINT` event to stop. |
|||
|
|||
```js |
|||
api |
|||
._devServer() |
|||
.then(() => console.log('Exiting process...')); |
|||
``` |
|||
@ -0,0 +1,99 @@ |
|||
# Neutrino CLI |
|||
|
|||
Using the command-line interface is the preferred way of interacting with Neutrino. Let's take a look at its usage. |
|||
|
|||
## `--help` |
|||
|
|||
Using `neutrino --help` will bring up the following help guide: |
|||
|
|||
```bash |
|||
❯ neutrino --help |
|||
Commands: |
|||
start Build a project in development mode |
|||
build Compile the source directory to a bundled build |
|||
test [files..] Run all suites from the test directory or provided files |
|||
|
|||
Options: |
|||
--presets A list of Neutrino presets used to configure the build [array] [default: []] |
|||
--version Show version number [boolean] |
|||
--help Show help [boolean] |
|||
``` |
|||
|
|||
## `--version` |
|||
|
|||
Using `--version` will output the current version of the Neutrino CLI to the console and exit. |
|||
|
|||
```bash |
|||
❯ neutrino --version |
|||
4.0.0 |
|||
``` |
|||
|
|||
## `--presets` |
|||
|
|||
The `--presets` flag can be used in conjunction with any of the top-level commands to specify a collection of |
|||
presets to load. These can be an npm package or a relative path to a module to load as a preset. |
|||
|
|||
```bash |
|||
❯ neutrino start --presets neutrino-preset-react neutrino-preset-karma |
|||
``` |
|||
|
|||
The Neutrino CLI will still attempt to load any presets defined in the project's package.json located at |
|||
`config.presets`. Presets passed via the CLI `--presets` will take precedence over presets defined in |
|||
`config.presets`, meaning that options set by package.json presets can have their values overridden by |
|||
`--presets` presets. |
|||
|
|||
## neutrino start |
|||
|
|||
Using the command `neutrino start` builds a project in development mode, also starting a development server or source |
|||
watcher depending on the preset or config options used. This command sets the `NODE_ENV` environment variable to |
|||
`development`. |
|||
|
|||
## neutrino build |
|||
|
|||
Using the command `neutrino build` builds a project in production mode, rendering static assets to the configured build |
|||
output destination. This command sets the `NODE_ENV` environment variable to `production`. |
|||
|
|||
## neutrino test |
|||
|
|||
Using the command `neutrino test` passes execution onto a test runner preset. It is up to the preset being used to |
|||
determine how source files are built or provided to tests. See your particular test preset for details. This |
|||
command sets the `NODE_ENV` environment variable to `test`. |
|||
|
|||
Looking at the `--help` for `neutrino test`: |
|||
|
|||
```bash |
|||
❯ neutrino test --help |
|||
neutrino test [files..] |
|||
|
|||
Options: |
|||
--presets A list of Neutrino presets used to configure the build [array] [default: []] |
|||
--version Show version number [boolean] |
|||
--help Show help [boolean] |
|||
--watch Watch source files for changes and re-run tests [boolean] [default: false] |
|||
``` |
|||
|
|||
Using the command `neutrino test` will execute every test file located in your |
|||
[testing directory](/project-layout#Testing). You may also provide to this command the specific test files you wish |
|||
to run individually. It is important to note that when combined with the `--presets` parameter, you should use two |
|||
dashes after the last preset to denote the end of the presets and the beginning of the test files. |
|||
|
|||
```bash |
|||
❯ neutrino test a_test.js b_test.js |
|||
``` |
|||
|
|||
```bash |
|||
❯ neutrino test --presets neutrino-preset-react neutrino-preset-karma -- a_test.js b_test.js |
|||
``` |
|||
|
|||
You can also pass a flag `--watch` to watch source files for changes and re-run tests, if your preset supports it. |
|||
|
|||
```bash |
|||
❯ neutrino test --watch |
|||
``` |
|||
|
|||
## Exit codes |
|||
|
|||
When the CLI creates an instance of Neutrino, it waits for all commands to either resolve or reject their Promise. |
|||
If the command succeeded, the CLI will exit with code `0`. If there was an error, the CLI will log the error |
|||
to the console and exit with code `1`. This makes it easier to use Neutrino commands for status reasons, such |
|||
as failing a pull request on continuous integration if any tests fail or if there are linter errors. |
|||
@ -0,0 +1,94 @@ |
|||
# Contributing |
|||
|
|||
### 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 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](/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 |
|||
and developing Neutrino. In return, we will show you respect in addressing your issue, assessing changes, |
|||
and helping you finalize your pull requests. |
|||
|
|||
### What we need |
|||
|
|||
There is always room for improvement and expansion in Neutrino. Some things that could always help: |
|||
|
|||
- Triaging and fixing bugs |
|||
- Adding tests to Neutrino which can help ensure it functions properly with new contributions |
|||
- Keeping core presets up to date with the best Webpack and Babel options |
|||
- Expanding documentation, writing tutorials, and creating example projects |
|||
- Something else, of course! |
|||
|
|||
### What we probably don't need |
|||
|
|||
While we are happy to review **any** contribution, there are some things that are best left as an external project: |
|||
|
|||
- _Additional presets_. While neutrino-dev does contain a number of core presets, we created and maintain these because |
|||
they were core to most of the projects we personally work on. If there are more presets you believe should be maintained |
|||
by the core, then feel free to raise an issue and we can discuss! Most likely though, additional presets can be |
|||
externally maintained and published to npm. It still has the same reach potential as bringing it into the core, without |
|||
raising the maintenance burden for Neutrino unnecessarily. |
|||
- _Scaffolding and boilerplates._ The goal of Neutrino is to remove over-reliance on boilerplates, instead opting to |
|||
push users into consuming presets. Neutrino itself will not add commands to scaffold out new projects or create |
|||
boilerplate repositories. We do keep a collection of examples-as-documentation for getting started with Neutrino |
|||
presets, but do not wish to govern project structure more than necessary. These types of projects can be maintained |
|||
externally. |
|||
|
|||
## Support |
|||
|
|||
Neutrino team members and contributors are here to help you! Should you need assistance or have questions in using |
|||
Neutrino or its core presets, please consider asking on Stack Overflow or other channel rather than filing issues. We |
|||
would prefer to keep our GitHub issues clear for bugs, feature requests, discussions, and relevant information related |
|||
to its development. |
|||
|
|||
## Guidelines |
|||
|
|||
- Please make a good-faith effort to ensure that code that goes into neutrino-dev follows the existing patterns and |
|||
quality that is already present in the repository. |
|||
- Create issues for any major changes and enhancements that you wish to make. Discuss things transparently and get |
|||
community feedback. |
|||
- Strive for code to be readable. Prefer following functional programming paradigms over object-oriented ones where |
|||
possible. |
|||
- Keep feature versions as small as possible, preferably one new feature per version. |
|||
|
|||
## 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. |
|||
|
|||
## Filing bugs and issues |
|||
|
|||
When filing an issue, try to answer these questions: |
|||
|
|||
- What version of Neutrino are you using? |
|||
- Are you trying to use any presets? If so, which ones, and what versions? |
|||
- Are you using the Yarn client or the npm client? What version? |
|||
- What version of Node.js are you using? |
|||
- What operating system are you using? |
|||
- What did you do? |
|||
- What did you expect to happen? |
|||
- What actually happened, contrary to your expectations? |
|||
|
|||
## Feature Requests or Enhancements |
|||
|
|||
Please file an issue describing your request in detail: |
|||
|
|||
- What is the goal of the change? |
|||
- What are the pros and cons of the change? |
|||
- Could this dramatically improve the experience of our users? |
|||
|
|||
Please be open to discussion, and we will respect your time by fairly evaluating your request. In the event that your |
|||
request is deemed to not be acceptable to move forward, please understand that isn't a criticism of you as a person, |
|||
but rather that the idea in its present form may not be right at this time. We respect you and your ideas, and will |
|||
always encourage contributors to continue to make proposals. |
|||
|
|||
## Code review process |
|||
|
|||
Code is reviewed by Neutrino team members for quality, conformance to existing patterns, and functionality. |
|||
@ -0,0 +1,74 @@ |
|||
# Contributor Covenant Code of Conduct |
|||
|
|||
## Our Pledge |
|||
|
|||
In the interest of fostering an open and welcoming environment, we as |
|||
contributors and maintainers pledge to making participation in our project and |
|||
our community a harassment-free experience for everyone, regardless of age, body |
|||
size, disability, ethnicity, gender identity and expression, level of experience, |
|||
nationality, personal appearance, race, religion, or sexual identity and |
|||
orientation. |
|||
|
|||
## Our Standards |
|||
|
|||
Examples of behavior that contributes to creating a positive environment |
|||
include: |
|||
|
|||
* Using welcoming and inclusive language |
|||
* Being respectful of differing viewpoints and experiences |
|||
* Gracefully accepting constructive criticism |
|||
* Focusing on what is best for the community |
|||
* Showing empathy towards other community members |
|||
|
|||
Examples of unacceptable behavior by participants include: |
|||
|
|||
* The use of sexualized language or imagery and unwelcome sexual attention or |
|||
advances |
|||
* Trolling, insulting/derogatory comments, and personal or political attacks |
|||
* Public or private harassment |
|||
* Publishing others' private information, such as a physical or electronic |
|||
address, without explicit permission |
|||
* Other conduct which could reasonably be considered inappropriate in a |
|||
professional setting |
|||
|
|||
## Our Responsibilities |
|||
|
|||
Project maintainers are responsible for clarifying the standards of acceptable |
|||
behavior and are expected to take appropriate and fair corrective action in |
|||
response to any instances of unacceptable behavior. |
|||
|
|||
Project maintainers have the right and responsibility to remove, edit, or |
|||
reject comments, commits, code, wiki edits, issues, and other contributions |
|||
that are not aligned to this Code of Conduct, or to ban temporarily or |
|||
permanently any contributor for other behaviors that they deem inappropriate, |
|||
threatening, offensive, or harmful. |
|||
|
|||
## Scope |
|||
|
|||
This Code of Conduct applies both within project spaces and in public spaces |
|||
when an individual is representing the project or its community. Examples of |
|||
representing a project or community include using an official project e-mail |
|||
address, posting via an official social media account, or acting as an appointed |
|||
representative at an online or offline event. Representation of a project may be |
|||
further defined and clarified by project maintainers. |
|||
|
|||
## Enforcement |
|||
|
|||
Instances of abusive, harassing, or otherwise unacceptable behavior may be |
|||
reported by contacting the project lead at eli@mozilla.com. All |
|||
complaints will be reviewed and investigated and will result in a response that |
|||
is deemed necessary and appropriate to the circumstances. The project team is |
|||
obligated to maintain confidentiality with regard to the reporter of an incident. |
|||
Further details of specific enforcement policies may be posted separately. |
|||
|
|||
Project maintainers who do not follow or enforce the Code of Conduct in good |
|||
faith may face temporary or permanent repercussions as determined by other |
|||
members of the project's leadership. |
|||
|
|||
## Attribution |
|||
|
|||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, |
|||
available at [http://contributor-covenant.org/version/1/4][version] |
|||
|
|||
[homepage]: http://contributor-covenant.org |
|||
[version]: http://contributor-covenant.org/version/1/4/ |
|||
@ -0,0 +1,178 @@ |
|||
# Developing Neutrino |
|||
|
|||
Developing and contributing to Neutrino and its core presets is done through our monorepo located at |
|||
https://github.com/mozilla-neutrino/neutrino-dev. The code is broken up into a couple different sections: |
|||
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. |
|||
|
|||
<a href="https://github.com/mozilla-neutrino/neutrino-dev/fork" target="_blank">Fork mozilla-neutrino/neutrino-dev on GitHub</a> |
|||
|
|||
Once that is done, you can clone your copy of the repository on your computer, replacing `USER` with the username |
|||
of the account you forked the repository to: |
|||
|
|||
```bash |
|||
❯ git clone git@github.com:USER/neutrino-dev.git |
|||
❯ 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] <package> <...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 <package> <...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 <package> <...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 |
|||
master branch and create a new branch for your changes. |
|||
|
|||
_Example: You want to create a core preset for JavaScript Standard Style. You need a new branch for this work._ |
|||
|
|||
```bash |
|||
❯ git checkout -b standard-style |
|||
Switched to a new branch 'standard-style' |
|||
``` |
|||
|
|||
While making changes, be sure to test your code out for expected operation. If possible or applicable, write a |
|||
test that can verify these changes in the future. |
|||
|
|||
## Submitting a pull request |
|||
|
|||
Once you are satisified with your changes, you should commit them and submit a pull request. Use `git add` |
|||
in order to add files that should be commited. Give your changes a descriptive but not overly verbose message. |
|||
|
|||
```bash |
|||
❯ git add . |
|||
❯ git commit -m "Feature: Adding new core preset for JavaScript Standard Style" |
|||
❯ git push origin standard-style |
|||
``` |
|||
|
|||
Now if you open the GitHub page for your repository, GitHub should display a button to open a pull request for |
|||
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! 🎉 |
|||
|
|||
## Receiving updates |
|||
|
|||
If you need to update your local copy of neutrino-dev to be in sync with the main neutrino-dev repository, you |
|||
will want to fetch upstream changes. Add the main neutrino-dev repo as an upstream to your local copy, then fetch |
|||
the latest changes from the master branch. |
|||
|
|||
```bash |
|||
❯ git checkout master |
|||
❯ git remote add upstream https://github.com/mozilla-neutrino/neutrino-dev.git |
|||
❯ git pull upstream master |
|||
``` |
|||
@ -0,0 +1,162 @@ |
|||
# Creating Neutrino Presets |
|||
|
|||
Creating Neutrino presets can solve a number of use cases in a manner which captures all the necessary configuration |
|||
and dependencies necessary to accomplish those use cases: |
|||
|
|||
- You find yourself needing to make the same modifications to all the projects you work on. |
|||
- Your team wants to adopt a managed set of linting rules across projects. |
|||
- You want to add functionality to the build pipeline that has not yet been encapsulated by an existing preset. |
|||
- You want to support building for more platforms than existing presets support. |
|||
|
|||
## Getting Started |
|||
|
|||
Neutrino presets are Node.js modules or packages that export a function which accepts a Neutrino instance. You can use |
|||
this instance to modify the configuration, provide your own, expose custom options for your preset, listen for build |
|||
events, and execute functionality. |
|||
|
|||
At a bare minimum, let's start with our package boilerplate for an empty Neutrino preset: |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
// ... |
|||
}; |
|||
``` |
|||
|
|||
If you are using Babel or Neutrino to build your preset (so meta) with ES modules: |
|||
|
|||
```js |
|||
export default neutrino => { |
|||
// ... |
|||
}; |
|||
``` |
|||
|
|||
## Configuring |
|||
|
|||
The Neutrino instance provided to your custom configurator has a `config` property that is an instance of |
|||
[webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). We won't go in-depth of all the configuration |
|||
possibilities here, but encourage you to check out the documentation for webpack-chain for instruction on your |
|||
particular use case. |
|||
|
|||
This `neutrino.config` is an accumulation of all configuration set up to this moment. Every Neutrino preset interacts |
|||
with and makes changes through this config, which is all available to your preset. |
|||
|
|||
## Events |
|||
|
|||
Neutrino exposes events for various stages of the build process your preset can hook into **if necessary**. |
|||
|
|||
- `prestart`: Triggered prior to creating a development bundle or launching a dev server. |
|||
- `start`: Triggered after the development bundle has finished or the dev server has been stopped. |
|||
- `prebuild`: Triggered prior to creating a production build. |
|||
- `build`: Triggered after the production build has completed. |
|||
- `pretest`: Triggered prior to invoking any test runners. |
|||
- `test`: Triggered when test runners can start, or after they have all completed. |
|||
|
|||
_Example: Log to the console when a build finishes._ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.on('build', () => console.log('whew!')); |
|||
}; |
|||
``` |
|||
|
|||
## Including and merging other presets |
|||
|
|||
If your preset depends on other Neutrino presets, or you are creating a preset that is a combination of multiple |
|||
presets, you can install them as dependencies and simply call them from your preset, providing them with your Neutrino |
|||
instance. When users install your preset, they will bring along your dependencies defined with your package without |
|||
needing to also include your extended presets in their own commands. |
|||
|
|||
_Example: Define a Neutrino preset which combines Node.js and Mocha presets._ |
|||
|
|||
```js |
|||
const node = require('neutrino-preset-node'); |
|||
const mocha = require('neutrino-preset-mocha'); |
|||
|
|||
module.exports = neutrino => { |
|||
node(neutrino); |
|||
mocha(neutrino); |
|||
|
|||
// neutrino.config now contains the accumulation of configuration from |
|||
// the Node.js and Mocha presets |
|||
}; |
|||
``` |
|||
|
|||
## Sample Preset: JavaScript Standard Style |
|||
|
|||
Let's create a preset from scratch which allows users to augment their project with |
|||
[JavaScript Standard Style](http://standardjs.com/). For this sample preset we are using |
|||
[Yarn](https://yarnpkg.com) for managing dependencies, but you may use the npm client if you desire. |
|||
|
|||
```bash |
|||
# Create a new directory for your project and change into it: |
|||
mkdir neutrino-preset-standard-style && cd neutrino-preset-standard-style |
|||
|
|||
# Initialize your project with a package.json: |
|||
yarn init --yes |
|||
|
|||
# Install the dependencies needed by our preset |
|||
yarn add standard-loader standard |
|||
|
|||
# Create the main file to the preset, e.g. index.js |
|||
touch index.js |
|||
``` |
|||
|
|||
Let's edit this `index.js` file to add our preset: |
|||
|
|||
```js |
|||
const path = require('path'); |
|||
|
|||
module.exports = neutrino => { |
|||
neutrino.config |
|||
.rule('lint') |
|||
.pre() |
|||
.test(/\.jsx?$/) |
|||
.include(path.join(process.cwd(), 'src')) |
|||
.loader('standard', require.resolve('standard-loader'), { |
|||
snazzy: false |
|||
}); |
|||
}; |
|||
``` |
|||
|
|||
## Custom Data |
|||
|
|||
If you want to expose custom options for your preset that are not appropriate to be stored in the Neutrino config, |
|||
there is a `neutrino.custom` object namespace you can attach to. This way you can document to others how they can |
|||
go about affecting how your preset works. |
|||
|
|||
_Example:_ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.custom.standardStyle = { |
|||
quiet: false, |
|||
logLevel: 'warn' |
|||
}; |
|||
|
|||
// ... |
|||
}; |
|||
``` |
|||
|
|||
## Working with paths |
|||
|
|||
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')` |
|||
|
|||
## 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, |
|||
GitHub, or another location, you can share the hard work put into abstracting away configuration and save everyone |
|||
in the community time and effort. As long as Neutrino can require your preset, it puts no restrictions on where |
|||
you want to host it. |
|||
@ -0,0 +1,18 @@ |
|||
# Neutrino Customization |
|||
|
|||
No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications |
|||
to the way your Neutrino preset is building your project. Neutrino provides two ways you can augment a preset in the |
|||
context of a project without resorting to creating and publishing an entirely independent preset. |
|||
|
|||
### Simple Customization |
|||
|
|||
By defining a configuration object within your package.json, Neutrino will merge this information with that provided by |
|||
your preset, effectively overriding those options with your custom data. |
|||
|
|||
### Advanced Customization |
|||
|
|||
You can also create a configuration override directly in your project which can extend the presets you are using. |
|||
|
|||
--- |
|||
|
|||
Continue for details on each technique. |
|||
@ -0,0 +1,85 @@ |
|||
# Advanced Neutrino Customization |
|||
|
|||
No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications |
|||
to the way your Neutrino preset is building your project. If you need more customization than can be afforded by |
|||
augmenting your project's package.json, consider using this advanced configuration guide to modify your build as |
|||
needed. |
|||
|
|||
## Creating a project-specific preset |
|||
|
|||
Neutrino configurations are backed by [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain), a library for |
|||
making modifications to a Webpack configuration using a fluent or chained API. When your project needs more advanced |
|||
build overrides, you will be interacting with this API in order to perform modifications. |
|||
|
|||
First, we need to create a project-specific preset to make these changes. This can either be a JS file or a directory |
|||
with an `index.js` file. Since Neutrino uses Node.js and Webpack for interacting with presets, it is helpful to |
|||
understand that this is a Node.js module. By exporting a function from your module, you will be provided with a Neutrino |
|||
instance for modifying the build. Let's create a file called `neutrino-custom.js` in the root of our example project: |
|||
|
|||
```js |
|||
// neutrino-custom.js |
|||
module.exports = neutrino => { |
|||
// ... |
|||
}; |
|||
``` |
|||
|
|||
At the moment our custom configurator isn't doing anything, but it does get us far enough to be able to tell Neutrino |
|||
to use it for additional configuration. Modify your package.json and add `neutrino-custom.js` as an additional preset. |
|||
|
|||
_Note: Neutrino will attempt to load this module relative to the current working directory, which should be the root of |
|||
your project._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"presets": [ |
|||
"neutrino-preset-react", |
|||
"neutrino-preset-karma", |
|||
"neutrino-custom.js" |
|||
] |
|||
}, |
|||
"scripts": { |
|||
"build": "neutrino build" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Other than actually changing the config, that is all the setup necessary for Neutrino to pick up your custom changes. |
|||
|
|||
## Configuring |
|||
|
|||
The Neutrino instance provided to your custom configurator has a `config` property that is an instance of |
|||
[webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). We won't go in-depth of all the configuration |
|||
possibilities here, but encourage you to check out the documentation for webpack-chain for instruction on your |
|||
particular use case. |
|||
|
|||
This `neutrino.config` is an accumulation of all configuration set up to this moment. Every Neutrino preset interacts |
|||
with and makes changes through this config, which is all available to you. For example, if you are using the presets |
|||
`neutrino-preset-react` and `neutrino-preset-karma`, any options set can be extended, manipulated, or removed. |
|||
|
|||
_Example: Neutrino's React preset adds `.jsx` as a module extension. Let's remove it._ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config.resolve.extensions.delete('.jsx'); |
|||
}; |
|||
``` |
|||
|
|||
_Example: Neutrino's Node.js preset uses `babel-preset-env` to support Node.js v6.9. Let's change it to support back to |
|||
v4.2. This preset has a rule named "compile" and a loader named "babel"._ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config.module |
|||
.rule('compile') |
|||
.loader('babel', ({ options }) => { |
|||
options.presets[0][1].targets.node = 4.2; |
|||
|
|||
return { options }; |
|||
}); |
|||
}; |
|||
``` |
|||
|
|||
Presets can also have their own custom data in addition to the Neutrino config. See your respective preset for details. |
|||
Again, rather than reiterate the documentation for [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain) here, |
|||
please refer to its documentation for all ways you can modify a config instance to solve your use cases. |
|||
@ -0,0 +1,238 @@ |
|||
# Simple Neutrino Customization |
|||
|
|||
No two JavaScript projects are ever the same, and as such there may be times when you will need to make modifications |
|||
to the way your Neutrino preset is building your project. By defining a configuration object within your package.json, |
|||
Neutrino will merge this information with that provided by your preset, effectively overriding those options with your |
|||
custom data. |
|||
|
|||
## Prepare package.json |
|||
|
|||
First, you will need to define a `config` section within your package.json. You |
|||
[may have already done this](/usage.md#using-multiple-presets) if you |
|||
specified your presets through the `config` as opposed to flags through `scripts`: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"presets": [ |
|||
"neutrino-preset-react", |
|||
"neutrino-preset-karma" |
|||
] |
|||
}, |
|||
"scripts": { |
|||
"start": "neutrino start", |
|||
"build": "neutrino build" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Add a new property to `config` named `neutrino`. This will be an object where we can provide configuration data: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"presets": [], |
|||
"neutrino": { |
|||
|
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Populate this object with configuration overrides. This is not a Webpack configuration, but rather a Neutrino-compatible |
|||
object based on [webpack-chain](https://github.com/mozilla-rpweb/webpack-chain). |
|||
|
|||
## Usage |
|||
|
|||
### Entries |
|||
|
|||
Add files to named entry points, or define new entry points. This is a key named `entry`, with a value being an object. |
|||
This maps to points to enter the application. At this point the application starts executing. |
|||
|
|||
_Example: Define an entry point named `vendor` that bundles React packages separately from the application code._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"entry": { |
|||
"vendor": [ |
|||
"react", |
|||
"react-dom", |
|||
"react-hot-loader", |
|||
"react-router-dom" |
|||
] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Module |
|||
|
|||
The `module` object defines how the different types of modules within a project will be treated. Any additional |
|||
properties attached to `module` not defined below will be set on the final module configuration. |
|||
|
|||
#### Module Rules |
|||
|
|||
Using `module.rule` creates rules that are matched to requests when modules are created. These rules can modify how the |
|||
module is created. They can apply loaders to the module, or modify the parser. |
|||
|
|||
Using `module.rule.loader` allows to you define the Webpack loader and its options for processing a particular rule. |
|||
This loader is usually a `dependency` or `devDependency` of your project. Each `loader` object can specify a property |
|||
for the string `loader` and an `options` object. |
|||
|
|||
_Example: Add LESS loading to the project._ |
|||
|
|||
```json |
|||
{ |
|||
"dependencies": { |
|||
"less": "^2.7.2", |
|||
"less-loader": "^2.2.3" |
|||
}, |
|||
"config": { |
|||
"neutrino": { |
|||
"module": { |
|||
"rule": { |
|||
"styles": { |
|||
"test": "/\\.less$/", |
|||
"loader": { |
|||
"less": { |
|||
"loader": "less-loader", |
|||
"options": { |
|||
"noIeCompat": true |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Output |
|||
|
|||
The `output` object contains a set of options instructing Webpack on how and where it should output your bundles, |
|||
assets, and anything else you bundle or load with Webpack. This option can be any property/value combination that |
|||
[Webpack accepts](https://webpack.js.org/configuration/output/). |
|||
|
|||
_Example: Change the public path of the application._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"output": { |
|||
"publicPath": "https://cdn.example.com/assets/" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Node |
|||
|
|||
Use `node` to customize the Node.js environment using polyfills or mocks: |
|||
|
|||
_Example: mock the `__filename` and `__dirname` Node.js globals._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"node": { |
|||
"__filename": "mock", |
|||
"__dirname": "mock" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### DevServer |
|||
|
|||
Use `devServer` to customize webpack-dev-server and change its behavior in various ways. |
|||
|
|||
_Example: gzip the application when serving and listen on port 9000._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"devServer": { |
|||
"compress": true, |
|||
"port": 9000 |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Resolve |
|||
|
|||
Use `resolve` to change how modules are resolved. When using `resolve.extensions` and `resolve.modules`, these should be |
|||
specified as arrays, and will be merged with their respective definitions used in inherited presets. Any additional |
|||
properties attached to `resolve` not defined below will be set on the final module configuration. |
|||
|
|||
_Example: Add `.mjs` as a resolving extension and specify modules are located in a `custom_modules` directory._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"resolve": { |
|||
"extensions": [".mjs"], |
|||
"modules": ["custom_modules"] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### ResolveLoader |
|||
|
|||
Use `resolveLoader` to change how loader packages are resolved. When using `resolveLoader.extensions` and |
|||
`resolveLoader.modules`, these should be specified as arrays, and will be merged with their respective definitions used |
|||
in inherited presets. Any additional properties attached to `resolveLoader` not defined below will be set on the final |
|||
module configuration. |
|||
|
|||
_Example: Add `.loader.js` as a loader extension and specify modules are located in a `web_loaders` directory._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"resolve": { |
|||
"extensions": [".loader.js"], |
|||
"modules": ["web_loaders"] |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Additional configuration |
|||
|
|||
Any top-level properties you set on `config.neutrino` will be added to the configuration. |
|||
|
|||
_Example: Change the Webpack performance options to error when exceeding performance budgets._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"performance": { |
|||
"hints": "error" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Advanced Configuration |
|||
|
|||
With the options defined above in your package.json, you can perform a variety of build customizations on a per-project |
|||
basis. In the event that you need more customization than what is afforded through JSON, consider either switching to |
|||
[advanced configuration](/customization/advanced.md), or [creating your own preset](/creating-presets.md). |
|||
@ -0,0 +1,208 @@ |
|||
# Neutrino Airbnb Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-airbnb-base` is a Neutrino preset that supports linting JavaScript projects with Airbnb's base ESLint |
|||
config, following the [Airbnb styleguide](https://github.com/airbnb/javascript). |
|||
|
|||
## Features |
|||
|
|||
- Zero upfront configuration necessary to start linting your project |
|||
- Modern Babel knowledge supporting ES modules, JSX (when used with React preset), Web and Node.js apps |
|||
- Highly visible during development, fails compilation when building for production |
|||
- Easily extensible to customize your project as needed |
|||
|
|||
## Requirements |
|||
|
|||
- Node.js v6.9+ |
|||
- Yarn or npm client |
|||
- Neutrino v4, Neutrino build preset |
|||
|
|||
## Installation |
|||
|
|||
`neutrino-preset-airbnb-base` can be installed via the Yarn or npm clients. Inside your project, make sure |
|||
`neutrino` and `neutrino-preset-airbnb-base` are development dependencies. You will also be using |
|||
another Neutrino preset for building your application source code. |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn add --dev neutrino-preset-airbnb-base |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm install --save-dev neutrino-preset-airbnb-base |
|||
``` |
|||
|
|||
## Project Layout |
|||
|
|||
`neutrino-preset-airbnb-base` 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. |
|||
|
|||
## Quickstart |
|||
|
|||
After adding the Airbnb preset to your Neutrino-built project, edit your project's package.json to add the preset for |
|||
linting **before** your build preset. For example, if you are building your project using `neutrino-preset-web`: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start --presets neutrino-preset-airbnb-base neutrino-preset-web", |
|||
"build": "neutrino build --presets neutrino-preset-airbnb-base neutrino-preset-web" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Start the app, then check your console for any linting errors. If everything is successful, you should see no errors in |
|||
the console. ESLint errors visible during development are reported, but will still continue to build and serve your |
|||
project. |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
|
|||
ERROR in ./src/index.js |
|||
|
|||
/web/src/index.js |
|||
7:1 warning Unexpected console statement no-console |
|||
7:14 error A space is required after '{' babel/object-curly-spacing |
|||
7:20 error Missing space before value for key 'hello' key-spacing |
|||
7:27 error A space is required before '}' babel/object-curly-spacing |
|||
|
|||
✖ 4 problems (3 errors, 1 warning) |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm start |
|||
|
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
|
|||
ERROR in ./src/index.js |
|||
|
|||
/web/src/index.js |
|||
7:1 warning Unexpected console statement no-console |
|||
7:14 error A space is required after '{' babel/object-curly-spacing |
|||
7:20 error Missing space before value for key 'hello' key-spacing |
|||
7:27 error A space is required before '}' babel/object-curly-spacing |
|||
|
|||
✖ 4 problems (3 errors, 1 warning) |
|||
``` |
|||
|
|||
## Building |
|||
|
|||
`neutrino-preset-airbnb-base` will cause errors to **fail your build** when creating a bundle via `neutrino build`. If |
|||
you want to ease introduction of this linting preset to your project, consider only adding it to your preset list for |
|||
`neutrino start` until all linting errors have been resolved. |
|||
|
|||
```bash |
|||
❯ yarn build |
|||
clean-webpack-plugin: /web/build has been removed. |
|||
Build completed in 1.287s |
|||
|
|||
./src/index.js |
|||
|
|||
/Users/eli/code/neutrino-examples/web/src/index.js |
|||
6:1 warning Unexpected console statement no-console |
|||
6:14 error A space is required after '{' babel/object-curly-spacing |
|||
6:16 error Missing space before value for key 'a' key-spacing |
|||
6:17 error A space is required before '}' babel/object-curly-spacing |
|||
|
|||
✖ 4 problems (3 errors, 1 warning) |
|||
|
|||
@ multi ./src/index.js |
|||
./src/index.js |
|||
Module build failed: Error: Module failed because of a eslint error. |
|||
|
|||
at lint (/Users/eli/code/neutrino-dev/packages/neutrino-preset-airbnb-base/node_modules/eslint-loader/index.js:115:17) |
|||
at Object.module.exports (/Users/eli/code/neutrino-dev/packages/neutrino-preset-airbnb-base/node_modules/eslint-loader/index.js:181:3) |
|||
@ multi ./src/index.js |
|||
error Command failed with exit code 1. |
|||
``` |
|||
|
|||
## Customizing |
|||
|
|||
To override the build configuration, start with the documentation on [customization](/customization/README.md). |
|||
`neutrino-preset-airbnb-base` 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: |
|||
|
|||
- `lint`: Lints JS and JSX files from the `src` directory using ESLint. Contains a single loader named `eslint`. |
|||
|
|||
### Simple customization |
|||
|
|||
By following the [customization guide](/customization/simple.md) and knowing the rule and loader IDs above, |
|||
you can override and augment the linting configuration directly from package.json. _Note: Using the simple customization |
|||
approach for linting changes can be verbose._ |
|||
|
|||
_Example: Turn off semicolons from being required as defined by the Airbnb rules._ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"module": { |
|||
"rule": { |
|||
"lint": { |
|||
"loader": { |
|||
"eslint": { |
|||
"options": { |
|||
"rules": { |
|||
"semi": "off" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Again, using simple customization for linting can be verbose. Consider using advanced customization if it suits your |
|||
project. |
|||
|
|||
### Advanced configuration |
|||
|
|||
By following the [customization guide](/customization/advanced.md) and knowing the rule and loader IDs above, |
|||
you can override and augment the build by creating a JS module which overrides the config. |
|||
|
|||
_Example: Turn off semicolons from being required as defined by the Airbnb rules._ |
|||
|
|||
```js |
|||
const merge = require('deepmerge'); |
|||
|
|||
module.exports = neutrino => { |
|||
neutrino.config |
|||
.rule('lint') |
|||
.loader('eslint', ({ options }) => { |
|||
return { |
|||
options: merge(options, { |
|||
rules: { |
|||
semi: 'off' |
|||
} |
|||
}) |
|||
}; |
|||
}); |
|||
}; |
|||
``` |
|||
|
|||
## 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-airbnb-base.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-airbnb-base |
|||
@ -1 +0,0 @@ |
|||
# heading |
|||
@ -0,0 +1,184 @@ |
|||
# 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 |
|||
- Source watching for re-running of tests on change |
|||
- 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`, `.test.js`, `_test.jsx`, or `.test.jsx`. |
|||
|
|||
## 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 |
|||
PASS test/simple_test.js |
|||
simple |
|||
✓ should be sane (2ms) |
|||
|
|||
Test Suites: 1 passed, 1 total |
|||
Tests: 1 passed, 1 total |
|||
Snapshots: 0 total |
|||
Time: 0.936s |
|||
Ran all test suites. |
|||
✨ Done in 2.12s. |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm test |
|||
|
|||
PASS test/simple_test.js |
|||
simple |
|||
✓ should be sane (2ms) |
|||
|
|||
Test Suites: 1 passed, 1 total |
|||
Tests: 1 passed, 1 total |
|||
Snapshots: 0 total |
|||
Time: 0.972s |
|||
Ran all test suites. |
|||
``` |
|||
|
|||
To run tests against files from your source code, simply import them: |
|||
|
|||
```js |
|||
import thingToTest from '../src/thing'; |
|||
``` |
|||
|
|||
For more details on specific Jest usage, please refer to their [documentation](https://facebook.github.io/jest/). |
|||
|
|||
## 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-jest` can watch for changes on your source directory and subsequently re-run tests. Simply use the |
|||
`--watch` flag with your `neutrino test` command. |
|||
|
|||
## Customizing |
|||
|
|||
To override the test configuration, start with the documentation on [customization](/customization/README.md). |
|||
`neutrino-preset-jest` 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 adopted Babel settings from other build presets. |
|||
Contains a single loader named `babel`. |
|||
|
|||
### Simple customization |
|||
|
|||
By following the [customization guide](/customization/simple.md) and knowing the rule, and loader IDs above, |
|||
you can override and augment the build directly from package.json. |
|||
|
|||
Jest configuration settings can also be modified directly from package.json, but it is not required. |
|||
`neutrino-preset-jest` will import Jest configuration from your package.json's `jest` object; the format is |
|||
defined on the [Jest documentation site](https://facebook.github.io/jest/docs/configuration.html). |
|||
|
|||
_Example: Turn off bailing on test failures._ |
|||
|
|||
```json |
|||
{ |
|||
"jest": { |
|||
"bail": false |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 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 also modify Jest settings by overriding with any options Jest accepts. In a standalone Jest project this is |
|||
typically done in the package.json file, but `neutrino-preset-jest` allows advanced configuration through this |
|||
mechanism as well. This is stored in the `neutrino.custom.jest` object, and takes the same configuration options as |
|||
outlined in the [Jest documentation](https://facebook.github.io/jest/docs/configuration.html). |
|||
|
|||
_Example: Create a global `__DEV__` variable set to `true` in all test environments._ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.custom.jest.globals = { |
|||
__DEV__: true |
|||
}; |
|||
}; |
|||
``` |
|||
|
|||
## 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 |
|||
@ -0,0 +1,188 @@ |
|||
# 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 |
|||
@ -0,0 +1,167 @@ |
|||
# 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'; |
|||
``` |
|||
|
|||
For more details on specific Mocha usage, please refer to their [documentation](http://mochajs.org/). |
|||
|
|||
## 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 |
|||
|
|||
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 |
|||
@ -1,5 +1,227 @@ |
|||
# 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. 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 |
|||
|
|||
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 |
|||
|
|||
@ -1 +1,272 @@ |
|||
# heading |
|||
# Neutrino React Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-react` is a Neutrino preset that supports building React web applications. |
|||
|
|||
## 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 |
|||
- Extends from [neutrino-preset-web](/presets/neutrino-preset-web/README.md) |
|||
- 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 |
|||
- Automatic creation of HTML pages, no templating necessary |
|||
- Hot module replacement support |
|||
- Production-optimized bundles with Babili minification and easy chunking |
|||
- Easily extensible to customize your project as needed |
|||
|
|||
## Requirements |
|||
|
|||
- Node.js v6.9+ |
|||
- Yarn or npm client |
|||
- Neutrino v4 |
|||
|
|||
## Installation |
|||
|
|||
`neutrino-preset-react` can be installed via the Yarn or npm clients. Inside your project, make sure |
|||
`neutrino` and `neutrino-preset-react` are development dependencies. You will also need React and React DOM for actual |
|||
React development. |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn add --dev neutrino neutrino-preset-react |
|||
❯ yarn add react react-dom |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm install --save-dev neutrino neutrino-preset-react |
|||
❯ npm install --save react react-dom |
|||
``` |
|||
|
|||
## Project Layout |
|||
|
|||
`neutrino-preset-react` 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, CSS stylesheets, images, and any other assets that would be available |
|||
to your compiled project. |
|||
|
|||
## Quickstart |
|||
|
|||
After installing Neutrino and the React 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 |
|||
``` |
|||
|
|||
This React preset exposes an element in the page with an ID of `root` to which you can mount your application. Edit |
|||
your `src/index.js` file with the following: |
|||
|
|||
```jsx |
|||
import React from 'react'; |
|||
import { render } from 'react-dom'; |
|||
|
|||
render(<h1>Hello world!</h1>, document.getElementById('root')); |
|||
``` |
|||
|
|||
Now edit your project's package.json to add commands for starting and building the application: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start --presets neutrino-preset-react", |
|||
"build": "neutrino build --presets neutrino-preset-react" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Start the app, then open a browser to the address in the console: |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
## Building |
|||
|
|||
`neutrino-preset-react` builds static 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: /react/build has been removed. |
|||
Build completed in 6.692s |
|||
|
|||
Hash: 7a83f769b15f88b80727 |
|||
Version: webpack 2.2.1 |
|||
Time: 6695ms |
|||
Asset Size Chunks Chunk Names |
|||
index.b615ea9e95317f530317.bundle.js 143 kB 0, 1 [emitted] index |
|||
manifest.2211d9c1970bbd3c952b.bundle.js 1.41 kB 1 [emitted] manifest |
|||
index.html 779 bytes [emitted] |
|||
✨ Done in 8.32s. |
|||
``` |
|||
|
|||
You can either serve or deploy the contents of this `build` directory as a static site. |
|||
|
|||
## Customizing |
|||
|
|||
To override the build configuration, start with the documentation on [customization](/customization/README.md). |
|||
`neutrino-preset-react` does not use any additional named rules, loaders, or plugins that aren't already in use by the |
|||
Web preset. See the [Web documentation customization](/presets/neutrino-preset-web#customizing) |
|||
for preset-specific configuration to override. |
|||
|
|||
### 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. |
|||
|
|||
#### Vendoring |
|||
|
|||
By defining an entry point in package.json named `vendor` you can split out external dependencies into a chunk separate |
|||
from your application code. When working with a React application, it is recommended to start out by splitting off |
|||
React and React DOM into the `vendor` chunk. |
|||
|
|||
_Example: Put React and React DOM into a separate "vendor" chunk:_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"entry": { |
|||
"vendor": [ |
|||
"react", |
|||
"react-dom" |
|||
] |
|||
} |
|||
} |
|||
}, |
|||
"dependencies": { |
|||
"react": "^15.4.2", |
|||
"react-dom": "^15.4.2" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Running the build again, you can contrast the bundles generated here with the one generated in the quick start: |
|||
|
|||
```bash |
|||
❯ yarn build |
|||
clean-webpack-plugin: /react/build has been removed. |
|||
Build completed in 6.726s |
|||
|
|||
Hash: 0468e662989da55bdc5e |
|||
Version: webpack 2.2.1 |
|||
Time: 6730ms |
|||
Asset Size Chunks Chunk Names |
|||
vendor.0b3c06ba6b2494d683ee.bundle.js 142 kB 0, 2 [emitted] vendor |
|||
index.d264625fd405d81cb995.bundle.js 276 bytes 1, 2 [emitted] index |
|||
manifest.29ee4d0db8f2534cc643.bundle.js 1.44 kB 2 [emitted] manifest |
|||
index.html 866 bytes [emitted] |
|||
✨ Done in 8.21s. |
|||
``` |
|||
|
|||
#### HTML files |
|||
|
|||
If you wish to override how HTML files are created for your React app, refer to the [relevant section on |
|||
neutrino-preset-web](/presets/neutrino-preset-web/README.md#html-files). |
|||
|
|||
_Example: Change the application mount ID from "root" to "app":_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"html": { |
|||
"appMountId": "app" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### Advanced configuration |
|||
|
|||
By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs from |
|||
neutrino-preset-web, you can override and augment the build by creating a JS module which overrides the config. |
|||
|
|||
#### Vendoring |
|||
|
|||
By defining an entry point named `vendor` you can split out external dependencies into a chunk separate |
|||
from your application code. |
|||
|
|||
_Example: Put React and React DOM into a separate "vendor" chunk:_ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config |
|||
.entry('vendor') |
|||
.add('react') |
|||
.add('react-dom'); |
|||
}; |
|||
``` |
|||
|
|||
## 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(( |
|||
<AppContainer> |
|||
<MyApp /> |
|||
</AppContainer> |
|||
), document.getElementById('root')); |
|||
|
|||
if (module.hot) { |
|||
module.hot.accept('./MyApp', load); |
|||
} |
|||
|
|||
load(); |
|||
``` |
|||
|
|||
## 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-react.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-react |
|||
|
|||
@ -1 +1,224 @@ |
|||
# heading |
|||
# Neutrino Web Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
`neutrino-preset-web` is a Neutrino preset that supports building generic applications for the web. |
|||
|
|||
## 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 |
|||
- Automatic creation of HTML pages, no templating necessary |
|||
- Hot module replacement support |
|||
- Production-optimized bundles with Babili minification and easy chunking |
|||
- Easily extensible to customize your project as needed |
|||
|
|||
## Requirements |
|||
|
|||
- Node.js v6.9+ |
|||
- Yarn or npm client |
|||
- Neutrino v4 |
|||
|
|||
## Installation |
|||
|
|||
`neutrino-preset-web` can be installed via the Yarn or npm clients. Inside your project, make sure |
|||
`neutrino` and `neutrino-preset-web` are development dependencies. |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn add --dev neutrino neutrino-preset-web |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm install --save-dev neutrino neutrino-preset-web |
|||
``` |
|||
|
|||
## Project Layout |
|||
|
|||
`neutrino-preset-web` 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, CSS stylesheets, images, and any other assets that would be available |
|||
to your compiled project. |
|||
|
|||
## Quickstart |
|||
|
|||
After installing Neutrino and the Web 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 |
|||
``` |
|||
|
|||
This Web preset exposes an element in the page with an ID of `root` to which you can mount your application. Edit |
|||
your `src/index.js` file with the following: |
|||
|
|||
```js |
|||
const app = document.createElement('main'); |
|||
const text = document.createTextNode('Hello world!'); |
|||
|
|||
app.appendChild(text); |
|||
document.getElementById('root').appendChild(app); |
|||
``` |
|||
|
|||
Now edit your project's package.json to add commands for starting and building the application: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start --presets neutrino-preset-web", |
|||
"build": "neutrino build --presets neutrino-preset-web" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Start the app, then open a browser to the address in the console: |
|||
|
|||
#### Yarn |
|||
|
|||
```bash |
|||
❯ yarn start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
#### npm |
|||
|
|||
```bash |
|||
❯ npm start |
|||
✔ Development server running on: http://localhost:5000 |
|||
✔ Build completed |
|||
``` |
|||
|
|||
## Building |
|||
|
|||
`neutrino-preset-web` builds static 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: /web/build has been removed. |
|||
Build completed in 0.779s |
|||
|
|||
Hash: 55c33df4cd1222a03505 |
|||
Version: webpack 2.2.1 |
|||
Time: 784ms |
|||
Asset Size Chunks Chunk Names |
|||
index.52f2d06086f51d21f9c9.bundle.js 213 bytes 0, 1 [emitted] index |
|||
manifest.c10c6464802bf71a2c3f.bundle.js 1.41 kB 1 [emitted] manifest |
|||
index.html 779 bytes [emitted] |
|||
✨ Done in 2.10s. |
|||
``` |
|||
|
|||
You can either serve or deploy the contents of this `build` directory as a static site. |
|||
|
|||
## Customizing |
|||
|
|||
To override the build configuration, start with the documentation on [customization](/customization/README.md). |
|||
`neutrino-preset-web` creates some conventions to make overriding the configuration easier once you are ready to make |
|||
changes. |
|||
|
|||
By default the Web 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 Web preset is optimized toward the use case of single-page |
|||
applications over multi-page applications. |
|||
|
|||
### 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`. |
|||
- `html`: Allows importing HTML files from modules. Contains a single loader named `file`. |
|||
- `css`: Allows importing CSS stylesheets from modules. Contains two loaders named `style` and `css`. |
|||
- `img`, `svg`, `ico`: Allows import image files from modules. Each contains a single loader named `url`. |
|||
- `woff`, `ttf`: Allows importing WOFF and TTF font files from modules. Each contains a single loader named `url`. |
|||
- `eot`: Allows importing EOT font files from modules. Contains a single loader named `file`. |
|||
|
|||
### Plugins |
|||
|
|||
The following is a list of plugins and their identifiers which can be overridden: |
|||
|
|||
- `env`: Injects the value of `NODE_ENV` into the application as `process.env.NODE_ENV`. |
|||
- `html`: Creates HTML files when building. Has various options that can be configured via package.json. |
|||
- `chunk`: Defines chunks for `manifest` and `vendor` entry points. Can be configured via package.json. |
|||
- `hot`: Enables hot module reloading. |
|||
- `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. |
|||
|
|||
#### Vendoring |
|||
|
|||
By defining an entry point in package.json named `vendor` you can split out external dependencies into a chunk separate |
|||
from your application code. |
|||
|
|||
_Example: Put lodash into a separate "vendor" chunk:_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"neutrino": { |
|||
"entry": { |
|||
"vendor": [ |
|||
"lodash" |
|||
] |
|||
} |
|||
} |
|||
}, |
|||
"dependencies": { |
|||
"lodash": "*" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
#### HTML files |
|||
|
|||
Under the hood `neutrino-preset-web` uses [html-webpack-template](https://www.npmjs.com/package/html-webpack-template) |
|||
for generating HTML files. If you wish to override how these files are creating, define an object in your package.json |
|||
at `config.html` with options matching the format expected by html-webpack-template. |
|||
|
|||
_Example: Change the application mount ID from "root" to "app":_ |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"html": { |
|||
"appMountId": "app" |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 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. |
|||
|
|||
#### Vendoring |
|||
|
|||
By defining an entry point named `vendor` you can split out external dependencies into a chunk separate |
|||
from your application code. |
|||
|
|||
_Example: Put lodash into a separate "vendor" chunk:_ |
|||
|
|||
```js |
|||
module.exports = neutrino => { |
|||
neutrino.config |
|||
.entry('vendor') |
|||
.add('lodash'); |
|||
}; |
|||
``` |
|||
|
|||
## 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-web.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-web |
|||
|
|||
@ -0,0 +1,39 @@ |
|||
# Project Layout |
|||
|
|||
Out of the box Neutrino presets expect a project to have a particular structure in order to make the |
|||
development process for new projects as quick as possible. This is broken up into three directories: |
|||
|
|||
- Source code |
|||
- Build assets |
|||
- Testing |
|||
|
|||
Each of these directories are set up via convention by a Neutrino preset, but each can be customized as |
|||
desired by overriding the preset's configuration or using a different preset. See |
|||
[Custom Configuration](/custom-configuration.md) for detailed instructions. |
|||
|
|||
## Source Code |
|||
|
|||
By default Neutrino presets expect all project source code to live in a directory named `src` in the |
|||
root of the project. This includes JavaScript files, CSS stylesheets, images, and any other assets |
|||
that would be available to your compiled project. |
|||
|
|||
When running your project or creating a build bundle, a preset will look for this `src` directory for |
|||
the entry point(s) to your application and use this as the relative location for finding other assets |
|||
necessary for creating your builds. |
|||
|
|||
## Build Assets |
|||
|
|||
When creating a build bundle, a preset will put the compiled assets, including any generated |
|||
JavaScript files, into a directory named `build` by default. Typically your Neutrino preset will copy |
|||
any non-JavaScript files from the source directory over to the build directory, allowing you to maintain |
|||
the same relative path structure for static assets as is used for the source files. |
|||
|
|||
Normally most projects will exclude checking in this build directory to source control. |
|||
Be sure to add this directory to your project's `.gitignore`, `.hgignore`, or similar file. |
|||
|
|||
## Testing |
|||
|
|||
Neutrino presets by default expect all tests to be located in a directory named `test`. In order to make the |
|||
separation between tests and test fixtures or harnesses easier to differentiate, Neutrino presets also |
|||
usually look for test files ending in `_test.js` or `.test.js`. See your specific test preset for more |
|||
detailed information about running tests and other conventions. |
|||
@ -1 +1,11 @@ |
|||
# Neutrino Jest Preset |
|||
# 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. |
|||
|
|||
## Documentation |
|||
|
|||
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 |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-jest |
|||
|
|||
@ -1 +1,11 @@ |
|||
# Neutrino Karma Preset |
|||
# 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. |
|||
|
|||
## Documentation |
|||
|
|||
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 |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-karma |
|||
|
|||
@ -1 +1,11 @@ |
|||
# Neutrino Mocha Preset |
|||
# 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. |
|||
|
|||
## Documentation |
|||
|
|||
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 |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-mocha |
|||
|
|||
@ -1,108 +1,12 @@ |
|||
# Neutrino Web Preset [![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url] |
|||
# Neutrino Web Preset [![NPM version][npm-image]][npm-url] |
|||
|
|||
This [neutrino](https://github.com/mozilla-neutrino/neutrino) preset enables building generic web |
|||
applications with a common configuration for Webpack, ESLint, Babel, Karma+Mocha, along with a |
|||
static local development server. |
|||
`neutrino-preset-web` is a Neutrino preset that supports building generic applications for the web. |
|||
|
|||
<sup>This preset extends the [neutrino-preset-base preset](https://github.com/mozilla-neutrino/neutrino-preset-base) by enhancing it with web-specific configuration.</sup> |
|||
## Documentation |
|||
|
|||
# Getting started |
|||
|
|||
Install neutrino and neutrino-preset-web as development dependencies in your project: |
|||
|
|||
```sh |
|||
# npm |
|||
npm install --save-dev neutrino neutrino-preset-web |
|||
|
|||
# yarn |
|||
yarn add neutrino neutrino-preset-web --dev |
|||
``` |
|||
|
|||
Modify your package.json scripts to use the web preset to build your project |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "neutrino-preset-web" |
|||
}, |
|||
"scripts": { |
|||
"start": "PORT=4000 neutrino start", |
|||
"build": "neutrino build", |
|||
"test": "neutrino test" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Add your source code to `src/`, which is compiled using Babel's es2015 preset. A number of loaders |
|||
are pre-configured, allowing you to use `import` and `export` for CSS, images, HTML, and JSON. |
|||
During development, run `npm start` or `yarn start` to start a local development server for running the application. |
|||
When you are ready to build your project into static assets, run `npm run build` or `yarn run build` which will create |
|||
a `build/` directory in the root of your project. |
|||
|
|||
If you would like to use testing in your project, create a `test/` directory, and write tests in |
|||
JS files with file names ending in `_test.js`, e.g. `test/homepage_test.js` or |
|||
`test/users/admin_test.js`. Run tests with `npm test` or `yarn test`, which will output results to the console, and |
|||
also creates test coverage to a `.coverage/` directory. |
|||
|
|||
# Overriding the preset |
|||
|
|||
There may be times where this preset works well for you, but you need to change some of the defaults |
|||
it provides. Maybe you don't like the opinion of the ESLint rules, or want to add more types of file |
|||
loading. Whatever the reason for needing changes, you can either create a custom preset based on |
|||
this one, or change the values on a project-by-project basis. |
|||
|
|||
To override in your project, create a new file to use as a preset which will modify the existing |
|||
one, e.g. `custom-preset.js`: |
|||
|
|||
```js |
|||
// bring in the existing preset |
|||
const preset = require('neutrino-preset-web'); |
|||
|
|||
// modify the preset |
|||
|
|||
// re-export the preset |
|||
module.exports = preset; |
|||
``` |
|||
|
|||
Now you can pass this file to neutrino to use as the new preset: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "custom-preset.js" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can also choose to load different presets for different targets if you so wish: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "custom-preset.js" |
|||
}, |
|||
"scripts": { |
|||
"start": "neutrino start", |
|||
"test": "neutrino test --preset some-other-preset", |
|||
"build": "neutrino build --preset neutrino-preset-web" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
# Overriding the default page template |
|||
|
|||
By default, HTML files are built using the template located in `src/template.ejs` in this repo. If |
|||
you wish to use a custom template or if the default just doesn't suit your needs, you can create a |
|||
`template.ejs` file in your `src/` directory, and this preset will pick it up automatically. |
|||
|
|||
# Technology |
|||
|
|||
* [neutrino-preset-base](https://www.npmjs.com/package/neutrino-preset-base) |
|||
* [html-webpack-plugin](https://www.npmjs.com/package/html-webpack-plugin) simplifies creation of HTML files to serve webpack bundles |
|||
* [webpack-dev-server](https://www.npmjs.com/package/webpack-dev-server) Serves a webpack app. Updates the browser on changes |
|||
* [Karma](https://www.npmjs.com/package/karma) Test Runner for JavaScript |
|||
|
|||
[npm-image]: https://badge.fury.io/js/neutrino-preset-web.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-web |
|||
[daviddm-image]: https://david-dm.org/mozilla-neutrino/neutrino-preset-web.svg |
|||
[daviddm-url]: https://david-dm.org/mozilla-neutrino/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 |
|||
[npm-url]: https://npmjs.org/package/neutrino-preset-web |
|||
|
|||
@ -1,158 +1,26 @@ |
|||
<p align="center"> |
|||
<img src="https://github.com/mozilla-neutrino/neutrino/raw/logo/neutrino.png" height="150" /> |
|||
</p> |
|||
<h1><p align="center"><a href="https://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1> |
|||
|
|||
<p align="center">Create and build modern JavaScript applications with zero initial configuration and minimal fuss.</p> |
|||
<p align="center"><a href="https://npmjs.org/package/neutrino"><img src="https://badge.fury.io/js/neutrino.svg"></a> <a href="https://david-dm.org/mozilla-neutrino/neutrino"><img src="https://david-dm.org/mozilla-neutrino/neutrino.svg"></a></p> |
|||
--- |
|||
### Create and build modern JavaScript applications with zero initial configuration |
|||
#### Think Webpack, but with presets. That's Neutrino. |
|||
|
|||
Neutrino is a helper tool which lets you build web and Node.js applications with shared |
|||
configurations. It intends to make the process of initializing and building projects much simpler by |
|||
providing minimal development dependencies. Neutrino uses Webpack to build both web and Node.js |
|||
projects by providing complete build presets which can be shared across targets and projects. You |
|||
can use neutrino base presets to get started building a variety of projects, create your own |
|||
presets by extending the neutrino code presets to be shared across your own projects or even by the |
|||
community. Presets can even be manipulated on a project-by-project basis to handle almost any build |
|||
situation your preset doesn't cover. |
|||
[![NPM version][npm-image]][npm-url] |
|||
|
|||
--- |
|||
|
|||
## Features |
|||
|
|||
- Preset-based Webpack building with development and production support |
|||
- Test web projects with Karma + Mocha, and Node.js projects with Mocha |
|||
|
|||
## Core Presets |
|||
|
|||
- [Web](https://github.com/mozilla-neutrino/neutrino-preset-web): Build modern, generic web applications |
|||
- [Node.js](https://github.com/mozilla-neutrino/neutrino-preset-node): Build modern Node.js applications |
|||
- [React](https://github.com/mozilla-neutrino/neutrino-preset-react): Build React-based web applications |
|||
|
|||
## Requirements |
|||
|
|||
- v3 (latest): Node.js v4+ and yarn |
|||
- v2: Node.js v4+ and npm |
|||
|
|||
## Getting started |
|||
|
|||
Neutrino projects require 2 development dependencies: neutrino itself and a build configuration |
|||
preset. Neutrino provides core presets for building generic web applications, Node.js, or React |
|||
applications. If these presets do not meet your needs, feel free to use a community-provided preset |
|||
or extend one of these presets to meet your needs. |
|||
|
|||
To get started using neutrino in your project, install neutrino and your preset as development |
|||
dependencies. In this example, we want to build a React application: |
|||
|
|||
```sh |
|||
npm install --save-dev neutrino neutrino-preset-react |
|||
``` |
|||
|
|||
With neutrino and your preset in place, modify the `scripts` in your package.json to use |
|||
neutrino for building the project: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "PORT=3000 neutrino start --preset neutrino-preset-react", |
|||
"test": "neutrino test --preset neutrino-preset-react", |
|||
"build": "neutrino build --preset neutrino-preset-react" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
By default, neutrino preset look for source code in `src/`, and tests in `test/`. Use your npm |
|||
scripts to start building! |
|||
|
|||
```sh |
|||
# Build the application in development mode |
|||
yarn start |
|||
|
|||
# Build the application and run any tests |
|||
yarn test |
|||
|
|||
# Build the application in production mode, outputting content to build/ |
|||
yarn run build |
|||
``` |
|||
|
|||
If you plan to use the same preset across all your script targets, you can add a `config` entry to |
|||
your package.json to specify this: |
|||
|
|||
```json |
|||
{ |
|||
"config": { |
|||
"preset": "neutrino-preset-react" |
|||
}, |
|||
"scripts": { |
|||
"start": "PORT=3000 neutrino start", |
|||
"test": "neutrino test", |
|||
"build": "neutrino build" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Overriding presets |
|||
|
|||
Neutrino core presets provide a good baseline for developing a few different types of JavaScript |
|||
applications by providing configuration for Webpack, ESLint, Karma, and Mocha. If you need to modify |
|||
preset configuration, you can `require` the preset in your project and specify a new preset to |
|||
neutrino with the changes. |
|||
|
|||
For example, let's say you have a project using the neutrino `web` preset, but now want to support |
|||
building LESS files. Let's create a new custom preset in your project to handle this, e.g. |
|||
`custom-preset.js`: |
|||
|
|||
```js |
|||
// require the preset to change |
|||
const preset = require('neutrino-preset-web'); |
|||
// also a using helper to deep-copy an object |
|||
const clone = require('lodash.clonedeep'); |
|||
|
|||
// Find the preset's CSS loader |
|||
const cssLoader = preset.module.loaders.find(l => /css/.test(l.test)); |
|||
|
|||
// Make a copy of the loader so we can use it for LESS loading, while still keeping normal |
|||
// CSS loading |
|||
const lessLoader = clone(cssLoader); |
|||
|
|||
// Change the files the loader uses to .less files |
|||
lessLoader.test = /\.less$/; |
|||
|
|||
// Add the less-loader to this loader which handles LESS compilation |
|||
lessLoader.loaders.push(require.resolve('less-loader')); |
|||
|
|||
// Add the new LESS loader to the preset |
|||
preset.module.loaders.push(lessLoader); |
|||
|
|||
// re-export the modified preset |
|||
module.exports = preset; |
|||
``` |
|||
|
|||
Now use your new preset in your package.json scripts: |
|||
|
|||
```json |
|||
{ |
|||
"scripts": { |
|||
"start": "neutrino start -p custom-preset.js" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
# Creating shareable presets |
|||
|
|||
Creating neutrino presets uses the same premise as modifying a preset, but with the addition that |
|||
these can be published to npm and used in numerous projects. See the neutrino core presets for |
|||
examples on how this is accomplished for tips on creating your own presets. |
|||
|
|||
## Contribute |
|||
|
|||
- Issue Tracker: [https://github.com/mozilla-neutrino/neutrino/issues](https://github.com/mozilla-neutrino/neutrino/issues) |
|||
- Source Code: [https://github.com/mozilla-neutrino/neutrino](https://github.com/mozilla-neutrino/neutrino) |
|||
- Code of Conduct: [Adapted from Rust CoC](https://www.rust-lang.org/conduct.html) |
|||
Neutrino is a companion tool which lets you build web and Node.js applications with shared presets or configurations. |
|||
It intends to make the process of initializing and building projects much simpler by providing minimal development |
|||
dependencies. |
|||
|
|||
## Support |
|||
Neutrino uses Webpack to build both web and Node.js projects by providing complete build presets which can be shared |
|||
across targets and projects. You can use Neutrino base presets to get started building a variety of projects, create |
|||
your own presets by extending the Neutrino core ones to be shared across your own projects or even by the community. |
|||
Presets can even be manipulated on a project-by-project basis to handle almost any build situation your preset doesn't |
|||
cover. |
|||
|
|||
If you are having issues, please let us know. |
|||
## Documentation |
|||
|
|||
## License |
|||
See the [Neutrino docs](https://neutrino.js.org/) |
|||
for details on installation, getting started, usage, and customizing. |
|||
|
|||
This project is licensed under the [Mozilla Public License v2.0](https://github.com/mozilla-neutrino/neutrino/blob/master/LICENSE) |
|||
[npm-image]: https://badge.fury.io/js/neutrino.svg |
|||
[npm-url]: https://npmjs.org/package/neutrino |
|||
|
|||
Loading…
Reference in new issue