Understanding the npmbundlerrc Structure

The liferay-npm-bundler is configured via a .npmbundlerrc file placed in the widget project’s root folder. You can create a complete configuration manually or extend a configuration preset (via Babel).

See the default preset reference to learn how the default preset configures the liferay-npm-bundler.

The Structure

The .npmbundlerrc file has four possible phase definitions: copy-process, pre-process, post-process, and babel. These phase definitions are explained in more detail below:

Copy-Process: Defined with the copy-plugins property (only available for dependency packages). Specifies which files should be copied or excluded from each given package.

Pre-Process: Defined with the plugins property. Specifies plugins to run before the Babel phase is run.

Babel: Defined with the .babelrc definition. Specifies the .babelrc file to use when running Babel through the package’s .js files.

note

During this phase, Babel transforms package files (for example, to convert them to AMD format, if necessary), but doesn’t transpile them. In theory, you could also transpile them by configuring the proper plugins. We recommend transpiling before running the bundler, to avoid mixing both unrelated processes.

Post-Process: Defined with the post-plugins property. An alternative to using the pre-process phase, this specifies plugins to run after the Babel phase has completed.

Here’s an example of a .npmbundlerrc configuration:

{
    "exclude": {
        "*": [
            "test/**/*"
        ],
        "some-package-name": [
            "test/**/*",
            "bin/**/*"
        ],
        "another-package-name@1.0.10": [
            "test/**/*",
            "bin/**/*",
            "lib/extras-1.0.10.js"
        ]
    },
    "include-dependencies": [
        "isobject", "isarray"
    ],
    "output": "build",
    "verbose": false,
    "dump-report": true,
    "config": {
        "imports": {
            "npm-angular5-provider": {
                "@angular/common": "^5.0.0",
            "@angular/core": "^5.0.0"
            }
        }
    },
    "/": {
    "plugins": ["resolve-linked-dependencies"],
    ".babelrc": {
      "presets": ["liferay-standard"]
    },
    "post-plugins": [
            "namespace-packages",
            "inject-imports-dependencies"
        ]
    },
    "*": {
      "copy-plugins": ["exclude-imports"],
      "plugins": ["replace-browser-modules"],
      ".babelrc": {
        "presets": ["liferay-standard"]
      },
      "post-plugins": [
        "namespace-packages",
        "inject-imports-dependencies",
        "inject-peer-dependencies"
      ]
    },
    "packages": {
        "a-package-name": [
        "copy-plugins": ["exclude-imports"],
        "plugins": ["replace-browser-modules"],
        ".babelrc": {
          "presets": ["liferay-standard"]
        },
        "post-plugins": [
          "namespace-packages",
          "inject-imports-dependencies",
          "inject-peer-dependencies"
        ]
        ],
        "other-package-name@1.0.10": [
          "copy-plugins": ["exclude-imports"],
          "plugins": ["replace-browser-modules"],
          ".babelrc": {
            "presets": ["liferay-standard"]
          },
          "post-plugins": [
            "namespace-packages",
            "inject-imports-dependencies",
            "inject-peer-dependencies"
          ]
        ]
    }
}

note

Not all definition formats (*, some-package-name, and some-package-name@version) shown above are required. In most cases, the wildcard definition (*) is enough. The non-wildcard formats (some-package-name and some-package-name@version) are rare exceptions for packages that require a more specific configuration than the wildcard definition provides.

Standard Configuration Options

Below are the standard configuration options for the .npmbundlerrc file:

config: Defines the global configuration that is made available to all liferay-npm-bundler and Babel plugins. Please refer to each plugin’s documentation to find the available options for each specific plugin.

{
  "config": {
    "imports": {
      "vuejs-provider": {
        "vue": "^2.0.0"
      }
    }
  }
}

dump-report: Sets whether to generate a debugging report. If true, a liferay-npm-bundler-report.html file that describes all actions and decisions taken when processing project and npm modules is generated in the project directory. Note that you can also pass this as the build flag $ liferay-npm-bundler --dump-report or $ liferay-npm-bundler -r. The default value is false.

no-tracking: Sets whether to send usage analytics to our servers. Note that you can also pass this as a build flag with the CLI argument $ liferay-npm-bundler --no-tracking, or by creating a marker file called .liferay-npm-bundler-no-tracking in the project’s root folder or any of its ancestors, or by setting the environment variable LIFERAY_NPM_BUNDLER_NO_TRACKING=''. The default value is false.

output: By default the bundler writes packages to the standard Gradle resources folder: build/resources/main/META-INF/resources. Set this value to override the default output folder. Note that the dependency npm packages are placed in a node_modules folder inside the build folder. Note if create-jar is set, the default output folder is build.

preset: Specifies the liferay-npm-bundler preset to use as a base configuration. Note that if a .npmbundlerrc file is not provided, the default liferay-npm-bundler-preset-standard preset is used. All settings provided by the preset are inherited, but they can be overridden.

verbose: Sets whether to output detailed information about what the tool is doing to the console. The default value is false.

Package Processing Options

"/": plugins’ configuration for the project’s package.

"\": plugins’ configuration for dependency packages.

(asterisk): Defines the default plugin configuration for all npm packages. It contains four values identified by a corresponding key. Keys copy-plugins, plugins and post-plugins identify arrays of liferay-npm-bundler plugins to apply in the copy, pre and post process steps. Key .babelrc identifies an object specifying the configuration to use in the Babel step and has the same structure of a standard .babelrc file.

exclude: Defines glob expressions of files to exclude from bundling from all or specific packages. Each list is an array identified by one of the following keys: * (any package), {package name} (any version of the package), or {package name}@{version} (a specific version of a package). Below is an example configuration:

{
  "exclude": {
    "*": ["__tests__/**/*"],
    "is-object": ["test/**/*"],
    "is-array@1.0.1": ["test/**/*", "Makefile"]
  }
}

ignore: Skips processing the specified JavaScript files with Babel for the project. Here’s an example configuration:

{
  "ignore": ["lib/legacy/**/*.js"]
}

include-dependencies: Defines packages to include in bundling, even if they are not listed under the dependencies section of package.json. These packages must be available in the node_modules folder (i.e. installed manually, without saving them to package.json, or listed in the devDependencies section).

packages: Defines plugin configuration for npm packages, per package.

max-parallel-files: Defines the maximum number of files to process in parallel to avoid EMFILE errors (especially on Windows). The default value is 128.

process-serially: Note: removed since v 2.7.0. Replaced with max-parallel-files.

rules: Defines rules to apply to the projects source files with the loader. Rules must have a use array property that defines the loader to use, which can be specified using a package name or an object with loader and options properties if applicable, and one or more of the properties below:

• test: Defines a regular expression to filter files in the sources folders to determine whether to apply rules to them. The project-relative path of each eligible file is compared against the regular expression and files that match are processed by the loaders.
• exclude: Refines the test expression by specifying files to exclude.
• include: Refines the test expression by specifying files to include.

Here’s an example configuration:

{
  "rules": [
    {
      "test": "\\.js$",
      "exclude": "node_modules",
      "use": [
        {
          "loader": "babel-loader",
          "options": {
            "presets": ["env", "react"]
          }
        }
      ]
    },
    {
      "test": "\\.css$",
      "use": ["style-loader"]
    },
    {
      "test": "\\.json$",
      "use": ["json-loader"]
    }
  ]
}

sources: Rules apply to files in these project folders. Folders can be nested (e.g. /src/main/resources/) and must be written using POSIX path separators (i.e. use / instead of \ on Win32 systems). Note that rules are automatically applied to package dependency files of the project.

Here’s an example configuration:

{
  "sources": ["src", "assets"]
}

OSGi Bundle Creation Options

Since version 2.2.0, the liferay-npm-bundler can create widget OSGi bundles for you.

• create-jar: Creates an OSGi bundle when set to a truthy value. When set to true, all sub-options take default values. When an object is passed, each sub-option can be configured individually. Note that you can also pass this as a build flag: $ liferay-npm-bundler --create- or $ liferay-npm-bundler -j. The default value is false.

{
  "create-jar": true
}

• create-jar.auto-deploy-portlet: This option is deprecated. Use the create-jar.features.js-extender option instead.

• create-jar.features.configuration: Specifies the file describing the system (OSGi) and widget instance (widget preferences, as defined in the Portlet spec) configuration to use. The default value is features/configuration.json if that file exists, otherwise the default is undefined.

{
  "create-jar": {
    "features": {
      "configuration": "features/configuration.json"
    }
  }
}

• create-jar.output-dir: Specifies where to place the final JAR.

{
  "create-jar": {
    "output-dir": "dist"
  }
}

• create-jar.features.js-extender: Controls whether to process the OSGi bundle with the JS Portlet Extender. You can also specify the minimum required version of the Extender to use for the bundle. This can be useful if you want to use advanced features in your bundle, but you want it to be deployable in older versions of the Extender. Pass the string "any" to let the bundle deploy in any version of the Extender. If true, the liferay-npm-bundler automatically determines the minimum version of the Extender required for the features used in the bundle. The default value is true. Here’s an example configuration:

{
  "create-jar": {
    "features": {
      "js-extender": "1.1.0"
    }
  }
}

• create-jar.features.web-context: Specifies the context path to use for publishing bundle’s static resources. The default value is /{project name}-{project version}.

{
  "create-jar": {
    "features": {
      "web-context": "/my-project"
    }
  }
}

• create-jar.features.localization: Specifies the L10N file to use for the bundle. The default value is features/localization/Language if a properties file with that base name exists, otherwise the default is undefined.

{
  "create-jar": {
    "features": {
      "localization": "features/localization/Language"
    }
  }
}

• create-jar.features.settings: This option is deprecated. Use the create-jar.features.configuration option instead.

note

Plugins’ configuration specifies the options for configuring plugins in all the possible phases, as well as the .babelrc file to use when running Babel (see Babel’s documentation for more information on that file format).

note

Prior to version 1.4.0 of the liferay-npm-bundler, package configurations were placed next to the tools options (*, output, exclude, etc.) To prevent package name collisions, package configurations are now namespaced and placed under the packages section. To maintain backwards compatibility, the liferay-npm-bundler falls back to the root section outside packages for package configuration, if no package configurations (package-name@version, package-name, or *) are found in the packages section.

Now you know the structure of the .npmbundlerrc file!