.npmbundlerrc file reference - liferay/liferay-js-toolkit GitHub Wiki

:warning: The contents of this wiki have been migrated to the liferay/liferay-frontend-projects monorepo and more specifically to the to the maintenance/projects/js-toolkit/docs directory. Development and updates will continue there, and this repo will be archived (ie. switched to read-only mode).

This page contains the whole reference for liferay-npm-bundler options. See How to use liferay-npm-bundler for a more detailed explanation on how to use the tool.

The options in this page are sorted alphabetically.

--create-jar

  • Description: same as create-jar true
  • Category: command line argument
  • Type: flag
  • See also:
  • Example:
$ liferay-npm-bundler --create-jar

--dump-report

$ liferay-npm-bundler --dump-report

--no-tracking

$ liferay-npm-bundler --no-tracking

-j

$ liferay-npm-bundler -j

-r

$ liferay-npm-bundler -r

* (asterisk)

  • Description: Defines 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 be used in the Babel step and has the same structure of a standard .babelrc file.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
  • Example:
{
  "*": {
    "copy-plugins": ["exclude-imports"],
    "plugins": ["replace-browser-modules"],
    ".babelrc:": {
      "presets": ["liferay-standard"]
    },
    "post-plugins": [
      "namespace-packages",
      "inject-imports-dependencies",
      "inject-peer-dependencies"
    ]
  }
}

.liferay-npm-bundler-no-tracking

$ touch .liferay-npm-bundler-no-tracking
$ liferay-npm-bundler

/ (forward slash)

  • Description: Defines plugin configuration for project files. It contains three values identified by a corresponding key. Keys plugins and post-plugins identify arrays of liferay-npm-bundler plugins to apply in the pre and post process steps. Key .babelrc identifies an object specifying the configuration to be used in the Babel step and has the same structure of a standard .babelrc file.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
  • Example:
{
  "/": {
    "plugins": ["resolve-linked-dependencies"],
    ".babelrc:": {
      "presets": ["liferay-standard"]
    },
    "post-plugins": ["namespace-packages", "inject-imports-dependencies"]
  }
}

config

  • Description: Defines global configuration that is made available to all liferay-npm-bundler and babel plugins. See the description of the plugins you use in your build to know what to put in this section.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
  • Example:
{
  "config": {
    "imports": {
      "vuejs-provider": {
        "vue": "^2.0.0"
      }
    }
  }
}

create-jar

  • Description: Activates OSGi bundle creation whenever it is set to a truthy value. When set to true all sub-options take default values; when set to an object, each sub-option can be tweaked separately.
  • Category: .npmbundlerrc
  • Type: object|boolean
  • Default: false
  • See also:
  • Example:
{
  "create-jar": true
}

create-jar.auto-deploy-portlet

create-jar.customManifestHeaders

  • Description: Defines custom headers to be written to the MANIFEST.MF file contained in the output JAR. Note that this is the same as create-jar.features.manifest but with lower precedence, i.e., values are combined but the the ones from the other section take precedence over the ones in this.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
  • See also:
  • Example:
{
  "create-jar": {
    "customManifestHeaders": {
      "Project-Name": "A Project",
      "Responsible": "[email protected]"
    }
  }
}

create-jar.features

  • Description: This section controls features of the OSGi bundle.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
  • Example:
{
  "create-jar": {
    "features": {
      "js-extender": true
    }
  }
}

create-jar.features.configuration

  • Description: Defines the file describing the system (OSGi) and portlet instance (portlet preferences, as defined in Porlet spec) configuration to use.
  • Category: .npmbundlerrc
  • Type: string
  • Default:
    • features/configuration.json if a file with that name exists
    • undefined otherwise
  • See also:
  • Example:
{
  "create-jar": {
    "features": {
      "configuration": "features/configuration.json"
    }
  }
}

create-jar.features.js-extender

  • Description: Controls whether to process the OSGi bundle with the JS Portlet Extender. In addition, since #237 it lets the developer specify the minimum required version of the Extender for the bundle to deploy. This can be useful if your bundle uses advances features but you still want it to be deployable in older versions of the Extender.
  • Category: .npmbundlerrc
  • Type: boolean|string
    • When a string is provided it can be:
      • A semantic version number specifying the minimum required version
      • The string any to let the bundle deploy in any version of the Extender
    • If true is provided, the bundler automatically determines the minimum vesion of the Extender needed, based on the features used by the bundle.
  • Default: true
  • Example:
{
  "create-jar": {
    "features": {
      "js-extender": "1.1.0"
    }
  }
}

create-jar.features.localization

  • Description: Defines the base name of the L10N files to use in the OSGi bundle.
  • Category: .npmbundlerrc
  • Type: string
  • Default:
    • features/localization/Language if a properties file with that base name exists
    • undefined otherwise
  • Example:
{
  "create-jar": {
    "features": {
      "localization": "features/localization/Language"
    }
  }
}

create-jar.features.manifest

  • Description: Defines the file containing custom headers to be written to the MANIFEST.MF file contained in the output JAR. Note that this is the same as create-jar.customManifestHeaders but with higher precedence, i.e., values are combined but the the ones from this section take precedence over the ones in the other.
  • Category: .npmbundlerrc
  • Type: string
  • Default:
    • features/manifest.json if a file with that name exists
    • undefined otherwise
  • See also:
  • Example:
{
  "create-jar": {
    "features": {
      "manifest": "features/manifest.json"
    }
  }
}

create-jar.features.settings

create-jar.features.web-context

  • Description: Defines the context path to use for publishing bundle's static resources.
  • Category: .npmbundlerrc
  • Type: string
  • Default: /{project name}-{project version}
  • Example:
{
  "create-jar": {
    "features": {
      "web-context": "/my-project"
    }
  }
}

create-jar.output-dir

  • Description: Defines where to place the final JAR.
  • Category: .npmbundlerrc
  • Type: string
  • Default: the value set in the output option
  • Example:
{
  "create-jar": {
    "output-dir": "dist"
  }
}

create-jar.output-filename

  • Description: Defines the name of the final JAR.
  • Category: .npmbundlerrc
  • Type: string
  • Default: <package name>-<version number>.jar
  • Example:
{
  "create-jar": {
    "output-filename": "my-bundle.jar"
  }
}

create-jar.web-context-path

dump-report

  • Description: Controls whether to dump a file named liferay-npm-bundler-report.html in the root project's folder that describes all actions and decissions taken when processing project and npm modules.
  • Category: .npmbundlerrc
  • Type: boolean
  • Default: false
  • See also:
  • Example:
{
  "dump-report": true
}

exclude

  • Description: Defines lists of glob expressions to match npm package files to exclude from output JAR. Each list is an array identified by a key that can be: * if the list applies to any package, {package name} if the list applies to any version of a specific package, or {package name}@{version} if the list applies to a specific version of a specific package.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
  • Example:
{
  "exclude": {
    "*": ["__tests__/**/*"],
    "is-object": ["test/**/*"],
    "[email protected]": ["test/**/*", "Makefile"]
  }
}

ignore

  • Description: Define glob expressions to match project's Javascript files that must not be processed by Babel.
  • Category: .npmbundlerrc
  • Type: array
  • Default: []
  • Example:
{
  "ignore": ["lib/legacy/**/*.js"]
}

include-dependencies

  • Description: Defines a list of package names to add to the output artifact even if they are not used by the project. Obviously, the packages must be present in the node_modules directory.
  • Category: .npmbundlerrc
  • Type: array
  • Default: []
  • Example:
{
  "include-dependencies": ["rxjs", "is-object"]
}

LIFERAY_NPM_BUNDLER_NO_TRACKING

$ export LIFERAY_NPM_BUNDLER_NO_TRACKING=''
$ liferay-npm-bundler

max-parallel-files

  • Description: Defines the maximum number of files to process in parallel to avoid EMFILE errors. See issue #298 for more information.
  • Category: .npmbundlerrc
  • Type: number
  • Default: 128
  • Example:
{
  "max-parallel-files": 32
}

no-tracking

{
  "no-tracking": true
}

osgi.Web-ContextPath

output

  • Description: Specifies the output directory of project's build. This directory is scanned by liferay-npm-bundler for the project's Javascript modules so, please note, that someone has to put them there (whether an npm script, gradle, maven, ...). Also, the dependency npm packages are placed in a node_modules folder inside this directory.
  • Category: .npmbundlerrc
  • Type: string
  • Default:
  • Example:
{
  "output": "build"
}

packages

  • Description: Defines specific per-package plugin configuration. Keys in the object can have two formats: {package name} or {package name}@{package version} depending on what they want to affect. Values of those keys have the same format as the * option.
  • Category: .npmbundlerrc
  • Type: object
  • Default: {}
👀 Note that, prior to version 1.4.0, the `packages` section did not exist and
   package configurations where placed outside of any section, next to other
   global options. This created the possibility of a collision and thus, the
   package configurations were namespaced. However, the tool still falls back
   to the root section (outside 'packages') to maintain backwards compatibility.
  • Example:
{
  "packages": {
    "is-object": {
      "copy-plugins": ["exclude-imports"],
      "plugins": ["replace-browser-modules"],
      ".babelrc:": {
        "presets": ["liferay-standard"]
      },
      "post-plugins": [
        "namespace-packages",
        "inject-imports-dependencies",
        "inject-peer-dependencies"
      ]
    }
  }
}

preset

  • Description: Defines the name of the preset to use as base configuration. All settings in that preset are inherited but can be overriden.
  • Category: .npmbundlerrc
  • Type: string
  • Default: liferay-npm-bundler-preset-standard
  • Example:
{
  "preset": "my-liferay-npm-bundler-base-preset"
}

process-serially

⚠ This option is not valid since 2.7.0. See #298 for more information.

rules

  • Description: Defines rules to apply to source files in order to generate output. See How to configure rules and loaders for more on this field.
  • Category: .npmbundlerrc
  • Type: array
  • Default: []
  • Example:
{
  "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

  • Description: Defines directories in the project that contain source files. The directories can be nested (f.e: 'src/main/resources') and must be written using POSIX path separators (i.e: use / in place of \ in win32 systems). The files in those directories are subject to rule appliance (see Loader rules).
  • Category: .npmbundlerrc
  • Type: array
  • Default: []
  • Example:
{
  "sources": ["src", "assets"]
}

verbose

  • Description: Controls whether to log messages about what the tool is doing to the console.
  • Category: .npmbundlerrc
  • Type: boolean
  • Default: false
  • Example:
{
  "verbose": true
}