{"id":13451,"library":"liferay-npm-bundler-plugin-replace-browser-modules","title":"Liferay Browser Module Alias Plugin","description":"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.","status":"deprecated","version":"2.32.2","language":"javascript","source_language":"en","source_url":"https://github.com/liferay/liferay-frontend-projects","tags":["javascript"],"install":[{"cmd":"npm install liferay-npm-bundler-plugin-replace-browser-modules","lang":"bash","label":"npm"},{"cmd":"yarn add liferay-npm-bundler-plugin-replace-browser-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add liferay-npm-bundler-plugin-replace-browser-modules","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for liferay-npm-bundler.","package":"liferay-npm-bundler","optional":false},{"reason":"Complements this plugin by handling local module aliasing within a package; this plugin only handles external redirections.","package":"babel-plugin-alias-modules"}],"imports":[{"note":"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.","wrong":"import { ReplaceBrowserModulesPlugin } from 'liferay-npm-bundler-plugin-replace-browser-modules'","symbol":"plugin entry","correct":"{ \"*\": { \"plugins\": [\"replace-browser-modules\"] } }"},{"note":"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.","symbol":"Configuration","correct":"{ \"resolve\": { \"aliasFields\": [\"browser\", \"module\"] } }"}],"quickstart":{"code":"{\n  \"*\": {\n    \"plugins\": [\"replace-browser-modules\"],\n    \"config\": {\n      \"resolve\": {\n        \"aliasFields\": [\"browser\"]\n      }\n    }\n  }\n}","lang":"json","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":"<2.32.0 (and potentially earlier versions from the same monorepo, prior to the fix)"},{"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.","message":"This 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Could not resolve module 'some-module' for browser environment"},{"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.","cause":"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.","error":"Uncaught SyntaxError: Cannot use import statement outside a module. / Uncaught SyntaxError: Unexpected token 'export'."},{"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.","cause":"The `resolve` object or `aliasFields` array within your `.npmbundlerrc` configuration for this plugin is malformed or missing.","error":"TypeError: Cannot read properties of undefined (reading 'aliasFields') in .npmbundlerrc"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}