Skip to content

Latest commit

 

History

History
1259 lines (915 loc) · 42.5 KB

Configuration.md

File metadata and controls

1259 lines (915 loc) · 42.5 KB
Raw

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(nwb) {
  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

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.proposals.all

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:

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'

browsers: String | Array<String> | Object

Configures Browserslist queries specifying the range of browsers your app supports.

This is used to configure @babel/preset-env (so it only transpiles the necessary ECMAScript 2015+ for your target browsers) and Autoprefixer (for managing vendor prefixes in your CSS).

If you don't configure this, nwb's default configuration is:

  • 'last 1 chrome version, last 1 firefox version, last 1 safari version' for development (when running a development server with nwb serve)
  • '>0.2%, not dead, not op_mini all' for production (when building your app with nwb build)

To override the defaults individually, configure an object with development or production properties:

module.exports = {
  browsers: {
    production: '>0.5%, not IE 11'
  }
}

If you configure a string or a list of strings, it will be used for both development and production:

module.exports = {
  browsers: [
    'last 2 chrome versions',
    'last 2 firefox versions',
    'last 2 safari versions',
    'IE 11'
  ]
}

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

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 all 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 ES 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.

proposals: Object | false

added in v0.24.0

Configures which experimental Babel plugins will be used via babel-preset-proposals.

By default, nwb enables:

  • class properties, which make ES classes more palatable, particularly for React-like components
  • @decorators, as used in libraries such as MobX.
  • namespace and default export extensions, which are useful for re-exporting modules from libraries

nwb's babel.loose config is also passed to the preset, so proposal plugins are in loose mode by default.

Provide an Object to configure the preset's options:

module.exports = {
  babel: {
    proposals: {
      pipelineOperator: true
    }
  }
}

Note: When running a Webpack build, @babel/plugin-syntax-dynamic-import will always be used independent of babel.proposals, to allow Babel to successfully parse dynamic import() statements so Webpack can handle them for code-splitting, so you probably never need to enable dynamicImport manually.

If you want to turn one of the default proposal plugins offs, you can pass a false property:

module.exports = {
  babel: {
    proposals: {
      decorators: false,
    }
  }
}

To disable use of babel-preset-proposals, configure proposals = false:

module.exports = {
  babel: {
    proposals: false
  }
}
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
    },
  }
}
react: String | Object

added in v0.24.4

Configure options for Babel's @babel/preset-react preset.

In addition to the existing classic mode, Babel v7.9.0 added a new automatic JSX transform to this preset, which:

  • currently requires the experimental version of React
  • uses new functions for instantiating JSX elements, which will allow optimizing them better in the future.
  • automatically imports the functions that JSX transpiles to.

If you just want to enable the new transform, you can use a String to specify the new 'automatic' runtime:

module.exports = {
  babel: {
    react: 'automatic'
  }
}

Use an Object if you need to configure any of the preset's other options.

Note: The preset's development option is automatically set for you depending on whether or not you're running a production build, no matter which runtime you use.

reactConstantElements: false

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

runtime: Object | false

changed in v0.24.0 - now only takes an Object to tweak config

Configure options for Babel's runtime transform plugin, which by default imports helper modules from @babel/runtime/helpers instead of duplicating helper code at the top of every module which needs it, and imports the regenerator runtime from @babel/runtime/regenerator required to use async/await or generators when needed.

Note: if you use async/await or generators in a React Component or Web Module project and are transpiling it to ES5 for publishing (which is the default), 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.

e.g. to enable importing of helper modules if you're publishing a large React Component library:

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

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

module.exports = {
  babel: {
    runtime: 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: Object

Configures Autoprefixer options for nwb's default PostCSS configuration.

If you want to configure the range of browsers prefix management is based on, the top-level browsers config is passed to Autoprefixer by default for its overrideBrowserslist option.

Provide an Object to configure any of Autoprefixer's other options.

e.g. if you want to enable grid prefixes for IE 10 and IE 11:

module.exports = {
  webpack: {
    autoprefixer: {
      grid: 'autoplace'
    }
  }
}
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 TerserWebpackPlugin settings via webpack.terser config, only webpack.terser.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:

  • lang - the language of document <html lang="">

    Default: 'en'

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

terser: Object | false

Configures options for TerserWebpackPlugin, which will be used when creating production builds.

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

{
  extractComments: false
}

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

module.exports = {
  webpack: {
    terser: {
      terserOptions: {
        mangle: false,
        beautify: true
      }
    }
  }
}

To completely disable use of Terser, set terser to false:

module.exports = {
  webpack: {
    terser: 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 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: ['ChromeHeadless']

A list of browsers to run tests in.

The launcher plugiun for Chrome is included with nwb, but requires that you have a version of Chrome installed in the environment the tests will be run in.

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 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 CommonJS and ES 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 ES modules build for use by bundlers when you run nwb build for a React component/library or web module project.

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

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

These are included automatically if you create a project with an ES 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

added in v0.23.0

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
 */