Registry / devops / liferay-npm-bundler-plugin-replace-browser-modules

liferay-npm-bundler-plugin-replace-browser-modules

library2.32.2jsnpmunverified

The `liferay-npm-bundler-plugin-replace-browser-modules` is a specialized plugin designed for the `liferay-npm-bundler`. Its core function is to facilitate the adaptation of Node.js modules for browser environments by processing the `browser` field (or other configured `aliasFields`) in `package.json` files. This allows developers to conditionally swap out or empty modules that are not browser-compatible, ensuring that frontend bundles are optimized for web usage within the Liferay DXP platform. The current stable version is 2.32.2. Updates for this plugin are typically aligned with the release cycle of the broader `liferay-frontend-projects` monorepo, which often sees multiple releases per quarter across its various sub-packages. It works in conjunction with `babel-plugin-alias-modules` to fully implement module aliasing, handling the external redirection part while the Babel plugin manages local requires. Its primary differentiator is its deep integration within the Liferay build toolchain, which is currently in a deprecated state, planned for future removal in Liferay 2024.Q4/Portal GA129.

devops

npm install liferay-npm-bundler-plugin-replace-browser-modules

github ↗package ↗

INSTALL

IMPORT

SIG · LIFERAY-NPM-BUNDLE

liferay-npm-bundler-plugin-replace-browser-modules

devopsjavascriptv2.32.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

plugin entry

✓ { "*": { "plugins": ["replace-browser-modules"] } }

✗ import { ReplaceBrowserModulesPlugin } from 'liferay-npm-bundler-plugin-replace-browser-modules'

This is a build-time plugin configured via `.npmbundlerrc`, not a runtime JavaScript module. The string 'replace-browser-modules' is used to reference it in the bundler configuration.

Configuration

✓ { "resolve": { "aliasFields": ["browser", "module"] } }

The plugin's behavior is configured under the `config` or plugin-specific section in `.npmbundlerrc`, typically using `resolve.aliasFields` to specify which `package.json` fields to process for aliases.

This `.npmbundlerrc` snippet adds `replace-browser-modules` as a plugin for all packages and explicitly configures it to use the `browser` field for aliasing. This is typically placed in the root of your Liferay widget project.

{ "*": { "plugins": ["replace-browser-modules"], "config": { "resolve": { "aliasFields": ["browser"] } } } }

Debug

Known issues

breakingThe plugin previously considered `unpkg` and `jsdelivr` fields in `package.json` for aliasing, but this behavior was removed due to causing problems. Relying on these fields for browser aliasing will no longer work.

fix

Explicitly configure `resolve.aliasFields` in your `.npmbundlerrc` if you need to alias fields other than the default `['browser']`. Ensure your `package.json` uses the `browser` field for browser-specific module replacements.

affects: <2.32.0 (and potentially earlier versions from the same monorepo, prior to the fix)

gotchaThis plugin only handles *external* module aliasing (redirecting existing modules or providing virtual ones when seen from another package). For *local* requires within a package to divert to a different target, `babel-plugin-alias-modules` is also required. Ignoring this distinction can lead to incomplete module resolution.

fix

Ensure both `liferay-npm-bundler-plugin-replace-browser-modules` and `babel-plugin-alias-modules` are correctly configured in your Liferay build process to achieve full module aliasing.

affects: >=2.0.0

deprecatedThe `liferay-npm-bundler` itself, and by extension its plugins, have been deprecated as of Liferay 2024.Q4/Portal GA129. It is planned for future removal, with Liferay recommending migration to standard JavaScript tooling like esbuild, webpack, or vite for module bundling.

fix

For new projects or ongoing maintenance, consider migrating away from `liferay-npm-bundler` and its ecosystem to modern build tools as suggested by Liferay documentation. Refer to Liferay's migration guides for transitioning existing projects.

affects: All versions

Errors

Common errors & fixes

Error: Could not resolve module 'some-module' for browser environment

The `browser` field in `package.json` or other configured `aliasFields` are not correctly pointing to a valid browser-compatible module, or the plugin is not correctly configured.

fix

Verify the `browser` field in the module's `package.json` points to an existing file. Check your `.npmbundlerrc` to ensure `replace-browser-modules` is listed under `plugins` and that `resolve.aliasFields` is correctly configured.

Uncaught SyntaxError: Cannot use import statement outside a module. / Uncaught SyntaxError: Unexpected token 'export'.

The `liferay-npm-bundler` expects third-party modules to be in CommonJS/ES5 format, but some libraries mix ES5 syntax with ES module `import`/`export` statements which the bundler doesn't understand.

fix

This is a known limitation of `liferay-npm-bundler` v2. Workarounds include transpiling modules to CommonJS using Babel before the bundler runs, or considering a migration to modern bundlers like Webpack or esbuild that natively support ES modules.

TypeError: Cannot read properties of undefined (reading 'aliasFields') in .npmbundlerrc

The `resolve` object or `aliasFields` array within your `.npmbundlerrc` configuration for this plugin is malformed or missing.

fix

Ensure your `.npmbundlerrc` has a valid `resolve` object with an `aliasFields` array, for example: `"config": { "resolve": { "aliasFields": ["browser"] } }` or within the plugin-specific configuration.

Upgrade

Version history

2.32.2latest on npm

Audit

Dependencies

liferay-npm-bundlerrequiredThis package is a plugin for liferay-npm-bundler.

babel-plugin-alias-modulesrequiredComplements this plugin by handling local module aliasing within a package; this plugin only handles external redirections.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/liferay/liferay-frontend-projects ↗

packagehttps://www.npmjs.com/package/liferay-npm-bundler-plugin-replace-browser-modules ↗