Liferay NPM Bundler Source Map Tweak Plugin

2.32.2 · active · verified Sun Apr 19

liferay-npm-bundler-plugin-tweak-sourcemaps (current stable version 2.32.2) is a specialized plugin designed for the Liferay DXP frontend development ecosystem. It integrates with liferay-npm-bundler to modify and correct source map paths after the bundling process, specifically for project-owned files. This addresses common issues where build artifacts generated by the Liferay NPM Bundler might have source map references that do not correctly align with the development environment, especially when deployed within an OSGi module context. The package is part of the larger `liferay-frontend-projects` monorepo, meaning its updates and maintenance are tied to the broader Liferay frontend tooling release cycle rather than having an independent cadence. Its key differentiator is its deep integration and targeted solution for source map pathing within the Liferay DXP development workflow, focusing solely on developer-authored source files and excluding third-party dependencies.

Common errors

```
Plugin 'tweak-sourcemaps' not found or invalid.
```
cause The plugin is either not installed as a development dependency, or its name is misspelled/incorrectly placed in the `.npmbundlerrc` configuration file.

fix Run `npm install --save-dev liferay-npm-bundler-plugin-tweak-sourcemaps` and ensure that `"plugins": ["tweak-sourcemaps"]` is correctly defined within your `.npmbundlerrc` file.
```
Browser's debugger shows minified code or incorrect file paths (e.g., 'webpack:///') when trying to debug my source code.
```
cause The `tweak-sourcemaps` plugin might not be correctly applied, or the observed issue stems from source maps of third-party dependencies, which this plugin is designed *not* to modify.

fix First, verify `.npmbundlerrc` for correct plugin configuration. Then, use your browser's developer tools to inspect the generated source maps to see the `sources` array and confirm the paths. Remember that this plugin explicitly does not affect third-party (e.g., `node_modules`) source maps.

Warnings

gotcha This plugin exclusively rewrites the `sources` field of source maps for *project-owned files* and explicitly excludes third-party dependencies. Developers expecting it to fix source map issues for `node_modules` will find it doesn't apply there.
Fix: Understand the plugin's scope; for third-party dependencies, external source map solutions or specific bundler configurations are needed.
gotcha Incorrect placement or misspelling of the 'tweak-sourcemaps' plugin name in the `.npmbundlerrc` file will result in the plugin not being loaded or executed, leading to un-tweaked source maps and potential debugging difficulties.
Fix: Verify the plugin name 'tweak-sourcemaps' is correctly listed within the `plugins` array in your `.npmbundlerrc` configuration file.
gotcha Changes in major versions of `liferay-npm-bundler` or updates to the underlying Liferay DXP build process might necessitate updates to this plugin or changes in its configuration. Being part of a monorepo, compatibility with other Liferay frontend tools is implicitly linked.
Fix: Always refer to the official Liferay frontend projects documentation and changelogs when upgrading Liferay DXP or `liferay-npm-bundler` to ensure plugin compatibility and address any breaking changes.
gotcha While effective for Liferay DXP specific source map pathing, this plugin might not resolve all complex or highly customized source map issues. Deeply nested or unusual build configurations could still require manual debugging.
Fix: Use browser developer tools to inspect source map paths (`sources` field) in the generated bundles to confirm they correctly map to your original files. Supplement with custom bundler configurations if the issue persists.

Install

npm install liferay-npm-bundler-plugin-tweak-sourcemaps npm
yarn add liferay-npm-bundler-plugin-tweak-sourcemaps yarn
pnpm add liferay-npm-bundler-plugin-tweak-sourcemaps pnpm

Imports

Configuration
```
This plugin is configured via the .npmbundlerrc file, not imported directly into JavaScript/TypeScript code.
```
As a liferay-npm-bundler plugin, it's enabled by adding its name to the 'plugins' array in your project's .npmbundlerrc. There are no direct ES module or CommonJS imports for the plugin itself, as it operates as a build-time configuration.

Quickstart

Installs the plugin as a development dependency and configures liferay-npm-bundler to use it by adding 'tweak-sourcemaps' to the plugins list in .npmbundlerrc. This example assumes a basic configuration without options.

npm install --save-dev liferay-npm-bundler-plugin-tweak-sourcemaps

// Then, add the following to your .npmbundlerrc file:
{
	"*": {
		"plugins": ["tweak-sourcemaps"]
	}
}

view raw JSON →