From 1584438726f82163a31d414f0189d1f6b2afe871 Mon Sep 17 00:00:00 2001 From: Eli Perelman Date: Wed, 15 Feb 2017 13:27:57 -0600 Subject: [PATCH] Updates --- api/index.html | 643 +++++++++++++++++++++ cli/index.html | 589 +++++++++++++++++++ contributing/code-of-conduct.html | 581 +++++++++++++++++++ contributing/development.html | 560 ++++++++++++++++++ contributing/index.html | 601 +++++++++++++++++++ creating-presets.md | 156 +++++ customization/advanced.html | 587 +++++++++++++++++++ customization/index.html | 534 +++++++++++++++++ customization/simple.html | 706 +++++++++++++++++++++++ index.html | 188 +++++- installation.html | 184 +++++- presets/index.html | 194 ++++++- presets/neutrino-preset-base/index.html | 185 +++++- presets/neutrino-preset-jest/index.html | 524 +++++++++++++++++ presets/neutrino-preset-karma/index.html | 524 +++++++++++++++++ presets/neutrino-preset-mocha/index.html | 524 +++++++++++++++++ presets/neutrino-preset-node/index.html | 181 +++++- presets/neutrino-preset-react/index.html | 177 +++++- presets/neutrino-preset-web/index.html | 177 +++++- project-layout.html | 553 ++++++++++++++++++ search_index.json | 2 +- usage.html | 242 +++++++- 22 files changed, 8490 insertions(+), 122 deletions(-) create mode 100644 api/index.html create mode 100644 cli/index.html create mode 100644 contributing/code-of-conduct.html create mode 100644 contributing/development.html create mode 100644 contributing/index.html create mode 100644 creating-presets.md create mode 100644 customization/advanced.html create mode 100644 customization/index.html create mode 100644 customization/simple.html create mode 100644 presets/neutrino-preset-jest/index.html create mode 100644 presets/neutrino-preset-karma/index.html create mode 100644 presets/neutrino-preset-mocha/index.html create mode 100644 project-layout.html diff --git a/api/index.html b/api/index.html new file mode 100644 index 0000000..1473b8d --- /dev/null +++ b/api/index.html @@ -0,0 +1,643 @@ + + + + + + + API · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + + + + + + +
+ +
+ +
+ + + + + + + + +
+
+ +
+
+ +
+ +

Neutrino API

+

When using Neutrino via the CLI, 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:

+
const Neutrino = require('neutrino');
+const api = new Neutrino(['neutrino-preset-react']);
+
+

Using ES imports:

+
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.

+
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. 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.

+
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.

+
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 watching 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.

+
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.

+
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.

+
api
+  .emitForAll('custom-event')
+  .then(() => console.log('All custom-events have resolved!'));
+
+

handleErrors(err, stats)

+

This method is used primarily 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.

+
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 received a SIGINT event to stop.

+
api
+  ._devServer()
+  .then(() => console.log('Exiting process...'));
+
+ + +
+ +
+
+
+ +

results matching ""

+
    + +
    +
    + +

    No results matching ""

    + +
    +
    +
    + +
    +
    + +
    + + + + + + + + + + + + + + +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/cli/index.html b/cli/index.html new file mode 100644 index 0000000..893a6c0 --- /dev/null +++ b/cli/index.html @@ -0,0 +1,589 @@ + + + + + + + CLI · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +
    + + + + + + + + +
    + +
    + +
    + + + + + + + + +
    +
    + +
    +
    + +
    + +

    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:

    +
    ❯ 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.

    +
    ❯ 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.

    +
    ❯ 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:

    +
    ❯ 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. 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.

    +
    ❯ neutrino test a_test.js b_test.js
+
    +
    ❯ 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.

    +
    ❯ 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.

    + + +
    + +
    +
    +
    + +

    results matching ""

    +
      + +
      +
      + +

      No results matching ""

      + +
      +
      +
      + +
      +
      + +
      + + + + + + + + + + + + + + +
      + + +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributing/code-of-conduct.html b/contributing/code-of-conduct.html new file mode 100644 index 0000000..4cfbfa2 --- /dev/null +++ b/contributing/code-of-conduct.html @@ -0,0 +1,581 @@ + + + + + + + Code of Conduct · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      +
      + + + + + + + + +
      + +
      + +
      + + + + + + + + +
      +
      + +
      +
      + +
      + +

      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, version 1.4, +available at http://contributor-covenant.org/version/1/4

      + + +
      + +
      +
      +
      + +

      results matching ""

      +
        + +
        +
        + +

        No results matching ""

        + +
        +
        +
        + +
        +
        + +
        + + + + + + + + + + + + + + +
        + + +
        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributing/development.html b/contributing/development.html new file mode 100644 index 0000000..d4caebf --- /dev/null +++ b/contributing/development.html @@ -0,0 +1,560 @@ + + + + + + + Development Process · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        +
        + + + + + + + + +
        + +
        + +
        + + + + + + + + +
        +
        + +
        +
        + +
        + +

        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.

        +

        Getting started

        +

        The first step to start developing neutrino-dev is forking the repository to your own GitHub account.

        +

        Fork mozilla-neutrino/neutrino-dev on GitHub

        +

        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:

        +
        ❯ git clone git@github.com:USER/neutrino-dev.git
+❯ cd neutrino-dev
+
        +

        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.

        +
        ❯ 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.

        +
        ❯ 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.

        +

        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.

        +
        ❯ git checkout master
+❯ git remote add upstream https://github.com/mozilla-neutrino/neutrino-dev.git
+❯ git pull upstream master
+
        +

        Congrats!

        +

        You just made a contribution to Neutrino! We are so happy to have your help! :tada:

        + + +
        + +
        +
        +
        + +

        results matching ""

        +
          + +
          +
          + +

          No results matching ""

          + +
          +
          +
          + +
          +
          + +
          + + + + + + + + + + +
          + + +
          + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/contributing/index.html b/contributing/index.html new file mode 100644 index 0000000..519adc8 --- /dev/null +++ b/contributing/index.html @@ -0,0 +1,601 @@ + + + + + + + Contributing · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
          +
          + + + + + + + + +
          + +
          + +
          + + + + + + + + +
          +
          + +
          +
          + +
          + +

          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 contribution and be part of our +team.

          +

          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, based on the +Contributor Covenant. 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 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.

          + + +
          + +
          +
          +
          + +

          results matching ""

          +
            + +
            +
            + +

            No results matching ""

            + +
            +
            +
            + +
            +
            + +
            + + + + + + + + + + + + + + +
            + + +
            + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/creating-presets.md b/creating-presets.md new file mode 100644 index 0000000..654b40a --- /dev/null +++ b/creating-presets.md @@ -0,0 +1,156 @@ +# 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' + }; + + // ... +}; +``` + +## Important Points + +- When working with paths, remember that your preset will be running in the context of a project. You should take care +to define application paths by referencing the current working directory with `process.cwd()`. For example if you +wanted to work with the project's "src" directory, you would merge the path via `path.join(process.cwd(), 'src)`. +- Because of package conflicts or unknown organization of a project's `node_modules` directory, it is usually safer to +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')`. + +## 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. diff --git a/customization/advanced.html b/customization/advanced.html new file mode 100644 index 0000000..8dff863 --- /dev/null +++ b/customization/advanced.html @@ -0,0 +1,587 @@ + + + + + + + Advanced · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            +
            + + + + + + + + +
            + +
            + +
            + + + + + + + + +
            +
            + +
            +
            + +
            + +

            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, 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:

            +
            // 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.

            +
            {
+  "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. 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.

            +
            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".

            +
            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 here, +please refer to its documentation for all ways you can modify a config instance to solve your use cases.

            + + +
            + +
            +
            +
            + +

            results matching ""

            +
              + +
              +
              + +

              No results matching ""

              + +
              +
              +
              + +
              +
              + +
              + + + + + + + + + + + + + + +
              + + +
              + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/customization/index.html b/customization/index.html new file mode 100644 index 0000000..f1df3b5 --- /dev/null +++ b/customization/index.html @@ -0,0 +1,534 @@ + + + + + + + Customization · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
              +
              + + + + + + + + +
              + +
              + +
              + + + + + + + + +
              +
              + +
              +
              + +
              + +

              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.

              + + +
              + +
              +
              +
              + +

              results matching ""

              +
                + +
                +
                + +

                No results matching ""

                + +
                +
                +
                + +
                +
                + +
                + + + + + + + + + + + + + + +
                + + +
                + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/customization/simple.html b/customization/simple.html new file mode 100644 index 0000000..3be5e9f --- /dev/null +++ b/customization/simple.html @@ -0,0 +1,706 @@ + + + + + + + Simple · Neutrino + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
                +
                + + + + + + + + +
                + +
                + +
                + + + + + + + + +
                +
                + +
                +
                + +
                + +

                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 if you +specified your presets through the config as opposed to flags through scripts:

                +
                {
+  "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:

                +
                {
+  "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.

                +

                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.

                +
                {
+  "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.

                +
                {
+  "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.

                +

                Example: Change the public path of the application.

                +
                {
+  "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.

                +
                {
+  "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.

                +
                {
+  "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.

                +
                {
+  "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.

                +
                {
+  "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.

                +
                {
+  "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, or creating your own preset.

                + + +
                + +
                +
                +
                + +

                results matching ""

                +
                  + +
                  +
                  + +

                  No results matching ""

                  + +
                  +
                  +
                  + +
                  +
                  + +
                  + + + + + + + + + + + + + + +
                  + + +
                  + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/index.html b/index.html index c337424..9eee833 100644 --- a/index.html +++ b/index.html @@ -126,7 +126,20 @@ -
                • +
                • + + + + + Project Layout + + + + + +
                  • + +
                • @@ -140,7 +153,7 @@ - +
                  • + +
                • + + - Overriding a preset + Customization + + + + + + + +
                  • + +
                • - Creating a preset + Creating presets + + + + + +
                  • + +
                • + + + + + API + + + + + +
                  • + +
                • + + + + + CLI + + + + + +
                  • + +
                • + + + + + Contributing + + + + + +