Configuration.md

Configuration

nwb's default setup can get you developing, testing and building production-ready apps and npm-ready components out of the box without any configuration.

If you need to tweak the default setup to suit your project's needs, or you want to use some of the other features the Babel, Karma and Webpack ecosystems have to offer, you can provide a configuration file.

You can also add new functionality by installing a plugin module.

Configuration File

By default, nwb will look for an nwb.config.js file in the current working directory for configuration.

You can also specify a configuration file using the --config option:

nwb --config ./config/nwb.js

This file should export either a configuration object...

module.exports = {
  // ...
}

...or a function which returns a configuration object when called:

module.exports = function(args) {
  return {
    // ...
  }
}

If a function is exported, it will be passed an object with the following properties:

• args: a parsed version of arguments passed to the nwb command
• command: the name of the command currently being executed, e.g. 'build' or 'test'
• webpack: nwb's version of the webpack module, giving you access to plugins bundled with Webpack.

Example Configuration Files

• bootstrap-4-nwb's nwb.config.js is a simple configuration file with minor tweaks to Babel and Webpack config.
• React Yelp Clone's nwb.config.js configures Babel, Karma and Webpack to allow nwb to be dropped into an existing app to handle its development tooling, reducing the amount of devDependencies and configuration which need to be managed.

Configuration Via Arguments

Configuration for the babel, webpack, devServer, karma and npm properties documented below can also be provided via arguments using dotted paths, instead of tweaking your nwb.config.js file for a single run, or instead of needing to add a config file for Quick Development commands:

nwb build-react-app --babel.stage=2

Note: If you have a config file, these arguments will act as overrides.

nwb uses minimist for argument parsing, so here's quick cheatsheet if you wish to make use of this functionality:

• --config.example is true
• --no-config.example is false
• --config.example=value is 'value'
• --config.example=one --config.example=two is ['one', 'two']

Configuration Object

The configuration object can include the following properties:

• nwb Configuration
  • type
  • polyfill - control automatic polyfilling
• Babel Configuration
  • babel
  • babel.cherryPick - enable cherry-picking for destructured import statements
  • babel.env - additional configuration for babel-preset-env
  • babel.loose - enable loose mode for Babel plugins which support it
  • babel.plugins - extra Babel plugins to be used
  • babel.presets - extra Babel presets to be used
  • babel.removePropTypes - disable or configure removal of React component propTypes in production builds
  • babel.reactConstantElements - disable use of React constant element hoisting in production builds
  • babel.runtime - enable the transform-runtime plugin with different configurations
  • babel.stage - control which experimental and upcoming JavaScript features can be used
  • babel.config - an escape hatch for manually editing the generated Babel config
• Webpack Configuration
  • webpack
  • webpack.aliases - rewrite certain import paths
  • webpack.autoprefixer - options for Autoprefixer
  • webpack.compat - enable Webpack compatibility tweaks for commonly-used modules
  • webpack.copy - patterns and options for CopyWebpackPlugin
  • webpack.debug - create a more debuggable production build
  • webpack.define - options for DefinePlugin, for replacing certain expressions with values
  • webpack.extractCSS - configure use of MiniCssExtractPlugin
  • webpack.html - options for HtmlPlugin
  • webpack.install - options for NpmInstallPlugin
  • webpack.publicPath - path to static resources
  • webpack.rules - tweak the configuration of generated Webpack rules and their loaders
    • Default Rules
    • Customising loaders
    • Disabling default rules
  • webpack.styles - customise creation of Webpack rules for stylesheets
  • webpack.uglify - configure use of Webpack's UglifyJsPlugin
  • webpack.extra - an escape hatch for extra Webpack config, which will be merged into the generated config
  • webpack.config - an escape hatch for manually editing the generated Webpack config
• Dev Server Configuration
  • devServer - configure Webpack Dev Server
• Karma Configuration
  • karma
  • karma.browsers - browsers tests are run in
  • karma.excludeFromCoverage - globs for paths which should be excluded from code coverage reporting
  • karma.frameworks - testing framework
  • karma.plugins - additional Karma plugins
  • karma.reporters - test results reporter
  • karma.testContext - point to a Webpack context module for your tests
  • karma.testFiles - patterns for test files
  • karma.extra - an escape hatch for extra Karma config, which will be merged into the generated config
  • karma.config - an escape hatch for manually editing the generated Karma config
• npm Build Configuration
  • npm
  • npm.cjs - toggle creation of a CommonJS build
  • npm.esModules - toggle creation of an ES modules build
  • UMD build
    • npm.umd - configure a UMD build which exports a global variable
      • umd.entry - use a different entry point for the UMD build
      • umd.global - global variable name exported by UMD build
      • umd.externals - dependencies to use via global variables in UMD build
    • package.json fields

type: String (required for generic build commands)

nwb uses this field to determine which type of project it's working with when generic build commands like build are used. If you're using commands which have the name of the type of project you're working with in them, you don't need to configure this.

If configured, it must be one of the following:

• 'inferno-app'
• 'preact-app'
• 'react-app'
• 'react-component'
• 'web-app'
• 'web-module'

polyfill: Boolean

For apps, nwb will provide polyfills for Promise, fetch and Object.assign by default.

To disable this, set polyfill to false:

module.exports = {
  polyfill: false
}

Babel Configuration

babel: Object

Babel configuration can be provided in a babel object, using the following properties.

For Webpack builds, any Babel config provided will be used to configure babel-loader - you can also provide additional configuration in webpack.rules if necessary.

cherryPick: String | Array<String>

Module names to apply import cherry-picking to.

This feature only works if you're using import syntax.

If you import a module with destructuring, the entire module will normally be included in your build, even though you're only using specific pieces:

import {This, That, TheOther} from 'some-module'

The usual workaround for this is to individually import submodules, which is tedious and bloats import sections in your code:

import This from 'some-module/lib/This'
import That from 'some-module/lib/That'
import TheOther from 'some-module/lib/TheOther'

If you use cherryPick config, you can keep writing code like the first example, but transpile to the same code as the second, by specifying the module name(s) to apply a cherry-picking transform to:

module.exports = {
  babel: {
    cherryPick: 'some-module'
  }
}

This is implemented using babel-plugin-lodash - please check its issues for compatibility problems with modules you're using cherryPick with and report any new ones you find.

env: Object

Additional options for babel-preset-env - nwb uses babel-preset-env to transpile ECMAScript features which aren't natively available in browsers yet.

loose: Boolean

Some Babel plugins have a loose mode in which they output simpler, potentially faster code rather than following the semantics of the ES6 spec closely.

nwb enables loose mode by default.

If you want to disable loose mode (e.g. to check your code works in the stricter normal mode for forward-compatibility purposes), set it to false.

e.g. to disable loose mode only when running tests:

module.exports = {
  babel: {
    loose: process.env.NODE_ENV === 'test'
  }
}

plugins: String | Array

Additional Babel plugins to use.

A single additional plugin which doesn't need a configuration object can be specified as a String, otherwise provide an Array.

nwb commands are run in the current working directory, so if you need to configure additional Babel plugins or presets, you can install them locally, pass their names and let Babel import them for you.

e.g. to install and use the babel-plugin-react-html-attrs plugin:

npm install babel-plugin-react-html-attrs

module.exports = {
  babel: {
    plugins: 'react-html-attrs'
  }
}

presets: String | Array

Additional Babel presets to use.

A single additional preset which doesn't need a configuration object can be specified as a String, otherwise provide an Array.

removePropTypes: Object | false

Since React propTypes are only used in development mode, nwb removes them from React app production builds by default using the react-remove-prop-types transform.

Set to false to disable use of this transform:

module.exports = {
  babel: {
    removePropTypes: false,
  }
}

Provide an object to configure the transform's options:

module.exports = {
  babel: {
    removePropTypes: {
      // Remove imports of the 'prop-types' module as well
      // Only safe to enable if you're only using this module for propTypes
      removeImport: true
    },
  }
}

reactConstantElements: false

Set this to false to disable use of the React constant element hoisting transform in React app production builds.

runtime: String | Boolean

Babel's runtime transform does 3 things by default:

1. Imports helper modules from babel-runtime instead of duplicating helpers in every module which needs them.
2. Imports a local polyfill for new ES6 built-ins (Promise) and static methods (e.g. Object.assign) when they're used in your code.
3. Imports the regenerator runtime required to use async/await when needed.

nwb's default config turns the regenerator runtime import on so you can use async/await and generators.

To enable an additional feature, you can name it (either 'helpers' or 'polyfill'):

module.exports = {
  babel: {
    runtime: 'helpers'
  }
}

To enable all features, set runtime to true.

To disable use of the runtime transform, set runtime to false.

Note: if you use async/await or enable the runtime transform's other features in a React Component or Web Module project, you will need to add babel-runtime to your package.json peerDependencies to ensure it can be resolved when somebody else uses your module from npm.

stage: Number | false

nwb implements its own equivalent of Babel 5's stage config for Babel 6

Controls which Babel preset will be used to enable use of experimental, proposed and upcoming JavaScript features in your code, grouped by the stage they're at in the TC39 process for proposing new JavaScript features:

Stage	TC39 Category	Features
0	Strawman, just an idea	do {...} expressions, :: function bind operator
1	Proposal: this is worth working on	export extensions
2	Draft: initial spec	class properties, @decorator syntax (using the Babel Legacy Decorator plugin) - enabled by default
3	Candidate: complete spec and initial browser implementations	object rest/spread ... syntax, async/await, ** exponentiation operator, trailing function commas

e.g. if you want to use export extensions in your app, you should set stage to 1:

module.exports = {
  babel: {
    stage: 1
  }
}

Stage 2 is enabled by default - to disable use of a stage preset entirely, set stage to false:

module.exports = {
  babel: {
    stage: false
  }
}

config: Function

Finally, if you need complete control, provide a babel.config() function which will be given the generated config.

Note: you must return a config object from this function.

module.exports = {
  webpack: {
    config(config) {
      // Change config as you wish

      // You MUST return the edited config object
      return config
    }
  }
}

Webpack Configuration

webpack: Object

Webpack configuration can be provided in a webpack object, using the following properties:

aliases: Object

Configures Webpack aliases, which allow you to control module resolution. Typically aliases are used to make it easier to import certain modules from within nested directories in an app.

module.exports = {
  webpack: {
    aliases: {
      // Enable use of 'img/file.png' paths in JavaScript and
      // "~images/file.png" paths in stylesheets to require an image from
      // src/images from anywhere in the the app.
      'img': path.resolve('src/images'),
      // Enable use of require('src/path/to/module.js') for top-down imports
      // from anywhere in the app, to promote writing location-independent
      // code by avoiding ../ directory traversal.
      'src': path.resolve('src')
    }
  }
}

You should be careful to avoid creating aliases which conflict with the names of Node.js built-ins or npm packages, as you will then be unable to import them.

autoprefixer: String | Object

Configures Autoprefixer options for nwb's default PostCSS configuration.

If you just need to configure the range of browsers prefix addition/removal is based on (nwb's default is >1%, last 4 versions, Firefox ESR, not ie < 9), you can use a String:

module.exports = {
  webpack: {
    autoprefixer: '> 1%, last 2 versions, Firefox ESR, ios >= 8'
  }
}

Use an Object if you need to set any of Autoprefixer's other options.

e.g. if you also want to disable removal of prefixes which aren't required for the configured range of browsers:

module.exports = {
  webpack: {
    autoprefixer: {
      remove: false,
    }
  }
}

You can check which browsers your Autoprefixer configuration will target using the browserl.ist service.

compat: Object

Certain libraries require specific configuration to play nicely with Webpack - nwb can take care of the details for you if you use a compat object to tell it when you're using them.

The following libraries are supported:

intl / moment / react-intl: String | Array | Object

changed in v0.21.0

If you use intl, Moment.js or react-intl in a Webpack build, all the locales they support will be imported by default and your build will be larger than you were expecting!

Provide an Array specifying language codes for the locales you want to load, or a String if you only need one locale.

For backwards-compatibility with older versions of nwb, locales can also be provided as an Object with a locales property.

---

Example config showing the use of multiple compat settings:

module.exports = {
  webpack: {
    compat: {
      moment: ['de', 'en-gb', 'es', 'fr', 'it']
    }
  }
}

copy: Array | Object

Configures CopyWebpackPlugin patterns and options.

By default, nwb uses CopyWebpackPlugin to copy any contents in an app's public/ directory to the output directory.

To add extra copy patterns, you can provide an Array of them:

module.exports = {
  webpack: {
    copy: [
      // Copy directory contents to output
      {from: 'path/to/mystuff'}
    ]
  }
}

To configure plugin options, provide an object with options or patterns properties:

module.exports = {
  webpack: {
    copy: {
      options: {
        debug: true
      },
      patterns: [
        {from: 'path/to/mystuff'}
      ]
    }
  }
}

debug: boolean

Enables a more debuggable production build:

• code which would normally be removed from a production build is removed, but code is not compressed.
• modules ids will be file system names rather than a generated hash.

It's recommended that you toggle this on via a configuration argument so you don't forget to remove it later:

npm run build -- --webpack.debug

nwb preact build app.js --webpack.debug

If you set debug in your config file, nwb will always display a hint to remind you to remove it later.

Note: if you've customised UglifyJsPlugin settings via webpack.uglify config, only webpack.uglify.compress will be used when a debug build is enabled.

define: Object

By default, nwb will use Webpack's DefinePlugin to replace all occurrences of process.env.NODE_ENV with a string containing NODE_ENV's current value.

You can configure a define object to add your own constant values.

e.g. to replace all occurrences of __VERSION__ with a string containing your app's version from its package.json:

module.exports = {
  webpack: {
    define: {
      __VERSION__: JSON.stringify(require('./package.json').version)
    }
  }
}

extractCSS: Object | false

added in v0.22.0

Configures MiniCssExtractPlugin options.

By default, nwb uses MiniCssExtractPlugin to extract imported stylesheets into .css files when creating a build.

Default configuration is to a chunk hash in extracted filenames, equivalent to:

module.exports = {
  webpack: {
    extractCSS: {
      filename: process.env.NODE_ENV === 'production' ? `[name].[contenthash:8].css` : '[name].css'
    }
  }
}

Set to false to disable extraction of .css files in builds (in which case style-loader will handle injecting <style> tags at runtime, as it does when running the development server).

html: Object

Configures options for HtmlWebpackPlugin.

For apps, nwb will look for a src/index.html template to inject <link> and <script> tags into for CSS and JavaScript bundles generated by Webpack.

Use templateconfig if you have an HTML file elsewhere you want to use:

module.exports = {
  webpack: {
    html: {
      template: 'html/index.html'
    }
  }
}

If you don't have a template at src/index.html or specify one via template, nwb will fall back to using a basic template which has the following properties you can configure:

• title - contents for <title>

  Default: the value of name from your app's package.json

• mountId - the id for the <div> provided for your app to mount itself into

  Default: 'app'

module.exports = {
  webpack: {
    html: {
      mountId: 'root',
      title: 'Unimaginative documentation example'
    }
  }
}

Other HtmlWebpackPlugin options can also be used. e.g. if you have a favicon.ico in your src/ directory, you can include it in the index.html generated when your app is built and have it copied to the output directory like so:

module.exports = {
  webpack: {
    html: {
      favicon: 'src/favicon.ico'
    }
  }
}

install: Object

Configures options for NpmInstallPlugin, which will be used if you pass an --install flag to nwb commands which run a development server.

publicPath: String

This is just Webpack's output.publicPath config pulled up a level to make it more convenient to configure.

publicPath defines the URL static resources will be referenced by in build output, such as <link> and <src> tags in generated HTML, url() in stylesheets and paths to any static resources you require() into your modules.

The default publicPath configured for most app builds is /, which assumes you will be serving your app's static resources from the root of whatever URL it's hosted at:

<script src="/app.12345678.js"></script>

If you're serving static resources from a different path, or from an external URL such as a CDN, set it as the publicPath:

module.exports = {
  webpack: {
    publicPath: 'https://cdn.example.com/myapp/'
  }
}

The exception is the React component demo app, which doesn't set a publicPath, generating a build without any root URL paths to static resources. This allows you to serve it at any path without configuration (e.g. on GitHub Project Pages), or open the generated index.html file directly in a browser, which is ideal for distributing app builds which don't require a server to run.

If you want to create a path-independent build, set publicPath to blank:

module.exports = {
  webpack: {
    publicPath: ''
  }
}

The trade-off for path-independence is HTML5 History routing won't work, as serving up index.html at anything but its real path will mean its static resource URLs won't resolve. You will have to fall back on hash-based routing if you need it.

rules: Object

Each Webpack rule generated by nwb has a unique id you can use to customise it:

module.exports = {
  webpack: {
    rules: {
      // Inline GIFs and PNGs smaller than 10KB
      graphics: {
        limit: 10000
      }
    }
  }
}

Rule configuration objects can contain rule options such as include and exclude (which control which files the rule applies to) and options for the rule's loader (which control what happens to the resource).

Loader options can be provided directly in the configuration object, as shown above, or you can use a nested options object.

Refer to the documentation of the Webpack loader used in each rule (linked to in default rules below) for options which can be configured.

Default Rules

Default rules generated by nwb and their associated ids are:

• babel - handles .js files with babel-loader

  Default config: {exclude: /node_modules/, options: {babelrc: false, cacheDirectory: true}}

• graphics - handles .gif, .png and .webp files using using url-loader

• svg - handles .svg files using using url-loader

• jpeg - handles .jpg and .jpeg files using url-loader

• fonts - handles .eot, .otf, .ttf, .woff and .woff2 files using url-loader

• video - handles .mp4, .ogg and .webm files using url-loader

• audio - handles .wav, .mp3, .m4a, .aac, and .oga files using url-loader

Default config for all url-loaders is {options: {limit: 1, name: '[name].[hash:8].[ext]'}}.

Default limit config prevents any files being inlined by default, while allowing you to configure url-loader to enable inlining if you need it.

See the Stylesheets documentation for default rules generated for stylesheets.

Customising loaders

Provide loader config for a rule to replace its loader:

module.exports = {
  webpack: {
    rules: {
      svg: {
        loader: 'svg-inline-loader',
        options: {classPrefix: true}
      }
    }
  }
}

To chain loaders, provide use config:

module.exports = {
  webpack: {
    rules: {
      svg: {
        use: [
          {
            loader: 'svg-inline-loader',
            options: {classPrefix: true}
          },
          'image-webpack-loader'
        ]
      }
    }
  }
}

Disabling default rules

To disable a default rule, set its id to false:

module.exports = {
  webpack: {
    rules: {
      svg: false
    }
  }
}

styles: Object | false

Configures how nwb creates Webpack config for importing stylesheets.

See the Stylesheets documentation for details.

uglify: Object | false

Configures options for Webpack's UglifyJsPlugin, which will be used when creating production builds.

Any additional options provided will be merged into nwb's defaults, which are:

{
  cache: true,
  parallel: true,
  sourceMap: true
}

For example, if you want to strip development-only code but keep the output readable for debugging:

module.exports = {
  webpack: {
    uglify: {
      uglifyOptions: {
        mangle: false,
        beautify: true
      }
    }
  }
}

To completely disable use of UglifyJS, set uglify to false:

module.exports = {
  webpack: {
    uglify: false
  }
}

extra: Object

Extra configuration to be merged into the generated Webpack configuration using webpack-merge - see the Webpack configuration docs for the available properties.

Note: Webpack 2 validates the structure of the config it's given, so providing invalid or unexpected config will break the build.

e.g. to add an extra rule which isn't managed by nwb's own webpack.rules config, you would need to provide a list of rules at webpack.extra.module.rules.

var path = require('path')

module.exports = function(nwb) {
  return {
    type: 'react-app',
    webpack: {
      extra: {
        // Example of adding an extra rule which isn't managed by nwb,
        // assuming you have installed html-loader in your project.
        module: {
          rules: [
            {test: /\.html$/, loader: 'html-loader'}
          ]
        },
        // Example of adding an extra plugin which isn't managed by nwb
        plugins: [
          new nwb.webpack.optimize.MinChunkSizePlugin({
            minChunkSize: 1024
          })
        ]
      }
    }
  }
}

config: Function

Finally, if you need complete control, provide a webpack.config() function which will be given the generated config.

Note: you must return a config object from this function.

module.exports = {
  webpack: {
    config(config) {
      // Change config as you wish

      // You MUST return the edited config object
      return config
    }
  }
}

Dev Server Configuration

nwb uses Webpack Dev Server to serve apps for development - you can tweak the options nwb uses and also enable additional features.

devServer: Object

Configuration for Webpack Dev Server - see Webpack's devServer config documentation for the available options.

Any devServer options provided will be merged on top of the following default options nwb uses:

{
  historyApiFallback: true,
  hot: true,
  noInfo: true,
  overlay: true,
  publicPath: webpackConfig.output.publicPath,
  quiet: true,
  watchOptions: {
    ignored: /node_modules/,
  },
}

Notable features you can configure using these options:

• devServer.historyApiFallback - configure disableDotRule if you need to use dots in your path when using the HTML5 History API.

• devServer.https - enable HTTPS with a default self-signed certificate, or provide your own certificates.

• devServer.overlay - disable the compile error overlay, or have it also appear for warnings.

• devServer.proxy - proxy certain URLs to a separate API backend development server.

• devServer.before - access the Express app to add your own middleware to the dev server.

e.g. to enable HTTPS:

module.exports = {
  devServer: {
    https: true
  }
}

Karma Configuration

nwb's default Karma configuration uses the Mocha framework and reporter plugins for it, but you can configure your own preferences.

Note: At runtime, Karma sets a usePolling autoWatch option to true if the platform is detected to be macOS or Linux. However, Karma's non-polling file-watching works correctly and consumes dramatically less CPU on macOS. nwb users on macOS will want to set usePolling: false within the extra: Object in the karma: config section of their nwb.config.js.

karma: Object

Karma configuration can be provided in a karma object, using the following properties:

browsers: Array<String | Plugin>

Default: ['PhantomJS']

A list of browsers to run tests in.

PhantomJS is the default as it's installed by default with nwb and should be able to run in any environment.

The launcher plugin for Chrome is also included, so if you want to run tests in Chrome, you can just name it:

module.exports = {
  karma: {
    browsers: ['Chrome']
  }
}

For other browsers, you will also need to supply a plugin and manage that dependency yourself:

module.exports = {
  karma: {
    browsers: ['Firefox'],
    plugins: [
      require('karma-firefox-launcher')
    ]
  }
}

nwb can also use the first browser defined in a launcher plugin if you pass it in browsers:

module.exports = {
  karma: {
    browsers: [
      'Chrome',
      require('karma-firefox-launcher')
    ]
  }
}

excludeFromCoverage: String | Array<String>

Default: ['test/', 'tests/', 'src/**/__tests__/']

Globs for paths which should be excluded from code coverage reporting.

frameworks: Array<String | Plugin>

Default: ['mocha']

Karma testing framework plugins.

You must provide the plugin for any custom framework you want to use and manage it as a dependency yourself.

e.g. if you're using a testing framework which produces TAP output (such as tape). this is how you would use frameworks and plugins props to configure Karma:

npm install --save-dev karma-tap

module.exports = {
  karma: {
    frameworks: ['tap'],
    plugins: [
      require('karma-tap')
    ]
  }
}

nwb can also determine the correct framework name given the plugin itself, so the following is functionally identical to the configuration above:

module.exports = {
  karma: {
    frameworks: [
      require('karma-tap')
    ]
  }
}

If a plugin module provides multiple plugins, nwb will only infer the name of the first plugin it provides, so pass it using plugins instead and list all the frameworks you want to use, for clarity:

module.exports = {
  karma: {
    frameworks: ['mocha', 'chai', 'chai-as-promised'],
    plugins: [
      require('karma-chai-plugins') // Provides chai, chai-as-promised, ...
    ]
  }
}

Note: If you're configuring frameworks and you want to use the Mocha framework plugin managed by nwb, just pass its name as in the above example.

plugins: Array<Plugin>

A list of plugins to be loaded by Karma - this should be used in combination with browsers, frameworks and reporters config as necessary.

reporters: Array<String | Plugin>

Default: ['mocha']

Customising reporters follows the same principle as frameworks, just using the reporters prop instead.

For built-in reporters, or nwb's version of the Mocha reporter, just pass a name:

module.exports = {
  karma: {
    reporters: ['progress']
  }
}

For custom reporters, install and provide the plugin:

npm install --save-dev karma-tape-reporter

module.exports = {
  karma: {
    reporters: [
      require('karma-tape-reporter')
    ]
  }
}

testContext: String

Use this configuration to point to a Webpack context module for your tests if you need to run code prior to any tests being run, such as customising the assertion library you're using, or global before and after hooks.

If you provide a context module, it is responsible for including tests via Webpack's require.context() - see the example in the Testing docs.

If the default testFiles config wouldn't have picked up your tests, you must also configure it so they can be excluded from code coverage.

testFiles: String | Array<String>

Default: .spec.js, .test.js or -test.js files anywhere under src/, test/ or tests/

Minimatch glob patterns for test files.

If karma.testContext is not being used, this controls which files Karma will run tests from.

This can also be used to exclude tests from code coverage if you're using karma.testContext - if the default testFiles patterns wouldn't have picked up your tests, configure this as well to exclude then from code coverage.

extra: Object

Extra configuration to be merged into the generated Karma configuration using webpack-merge.

Note: you must use Karma's own config structure in this object.

e.g. to tweak the configuration of the default Mocha reporter:

module.exports = {
  karma: {
    extra: {
      mochaReporter: {
        divider: '°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸',
        output: 'autowatch'
      }
    }
  }
}

config: Function

Finally, if you need complete control, provide a karma.config() function which will be given the generated config.

Note: you must return a config object from this function.

module.exports = {
  karma: {
    config(config) {
      // Change config as you wish

      // You MUST return the edited config object
      return config
    }
  }
}

npm Build Configuration

By default, nwb creates ES5 and ES6 modules builds for publishing to npm.

npm: Object

npm build configuration is defined in a npm object, using the following fields:

cjs: Boolean

Defaults to true if not provided.

Determines whether or not nwb will create a CommonJS build in lib/ when you run nwb build for a React component/library or web module project.

Set to false to disable this:

module.exports = {
  npm: {
    cjs: false
  }
}

esModules: Boolean

Defaults to true if not provided.

Determines whether or not nwb will create an ES6 modules build for use by ES6 module bundlers when you run nwb build for a React component/library or web module project.

When providing an ES6 modules build, you should also provide the following in package.json so compatible module bundlers can find it:

"module": "es/index.js",

These are included automatically if you create a project with an ES6 modules build enabled.

umd: String | Object | false

Configures a UMD build when you run nwb build for a React component/library or web module.

If you just need to configure the global variable the UMD build will export, you can use a String:

module.exports = {
  npm: {
    umd: 'MyLibrary'
  }
}

If you also have some external dependencies to configure, use an object containing the following properties:

entry: String

Specifies a module which will be the entry point for the UMD build. Otherwise the default entry (src/index.js) is used.

Currently, the UMD entry point must have a default export, but you might want to have named exports from the default entry point for people using your module via npm, e.g. if you're publishing a component library.

module.exports = {
  npm: {
    umd: {
      global: 'MyComponentLibrary',
      entry: './umd.js',
      externals: {
        'react': 'React'
      }
    }
  }
}

In this scenario, umd.js could import * a module which uses named exports and re-export its contents as default:

import * as components from './src/index.js'
export default components

global: String

The name of the global variable the UMD build will export.

externals: Object

A mapping from peerDependency module names to the global variables they're expected to be available as for use by the UMD build.

e.g. if you're creating a React component which also depends on React Router, this configuration would ensure they're not included in the UMD build:

module.exports = {
  npm: {
    umd: {
      global: 'MyComponent',
      externals: {
        'react': 'React',
        'react-router': 'ReactRouter'
      }
    }
  }
}

The UMD build can also be explicitly disabled by configuring umd = false.

package.json UMD Banner Configuration

A banner comment added to UMD builds will use as many of the following package.json fields as are present:

• name
• version
• homepage
• license

If all fields are present the banner will be in this format:

/*!
 * your-project v1.2.3 - https://github.com/you/your-project
 * MIT Licensed
 */