{"id":14669,"library":"liferay-npm-bundler-improved","title":"Liferay NPM Bundler Improved","description":"liferay-npm-bundler-improved is an unofficial, high-speed alternative to the official liferay-npm-bundler, designed to accelerate the development of Liferay portlets. Currently stable at version 1.5.1, its release cadence is feature-driven, with significant updates recently including beta phases for watch mode and localization. Key differentiators include drastically faster build times (around 0.1s on modern hardware) compared to the official bundler, an enhanced developer experience through a 'watch mode' with live instance replacement (primarily for Vite projects), comprehensive error reporting for common issues like missing `package.json` keys, and experimental localization support for `Liferay.Language.get()` functions within portlets. It also offers optional deployment automation and support for portlet instance configuration.","status":"active","version":"1.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/jwanner83/liferay-npm-bundler-improved","tags":["javascript","liferay","liferay-npm-bundler","npm-bundler","liferay-frontend"],"install":[{"cmd":"npm install liferay-npm-bundler-improved","lang":"bash","label":"npm"},{"cmd":"yarn add liferay-npm-bundler-improved","lang":"bash","label":"yarn"},{"cmd":"pnpm add liferay-npm-bundler-improved","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a Command Line Interface (CLI) tool. Its functionality is accessed by executing the 'liferay-npm-bundler-improved' command, typically via `npx` or as a script in `package.json`. It does not expose a JavaScript API for direct programmatic import.","wrong":"import * as bundler from 'liferay-npm-bundler-improved'","symbol":"liferay-npm-bundler-improved","correct":"npx liferay-npm-bundler-improved [options]"},{"note":"The watch mode feature is enabled through the `--watch` or `-w` CLI flag. There is no programmatic equivalent to activate or configure watch mode. Note that it requires Vite.","wrong":"import { enableWatchMode } from 'liferay-npm-bundler-improved'","symbol":"WatchMode","correct":"liferay-npm-bundler-improved --watch"},{"note":"Deployment is triggered using the `--deploy` or `-d` CLI flag. This feature requires the `LIFERAY_DEPLOYMENT_PATH` environment variable to be set. No programmatic deployment function is exposed.","wrong":"import { deployPortlet } from 'liferay-npm-bundler-improved'","symbol":"Deployment","correct":"liferay-npm-bundler-improved --deploy"}],"quickstart":{"code":"{\n  \"name\": \"my-liferay-portlet\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A sample Liferay portlet using liferay-npm-bundler-improved.\",\n  \"main\": \"src/index.js\",\n  \"scripts\": {\n    \"dev\": \"liferay-npm-bundler-improved -w --deploy\",\n    \"build\": \"liferay-npm-bundler-improved --copy-sources --copy-assets\"\n  },\n  \"keywords\": [\"liferay\", \"portlet\"],\n  \"devDependencies\": {\n    \"liferay-npm-bundler-improved\": \"^1.5.1\",\n    \"vite\": \"^5.0.0\" // Required for watch mode\n  },\n  \"license\": \"MIT\"\n}\n\n// To install dependencies:\n// pnpm i --D liferay-npm-bundler-improved vite\n\n// To use in development with watch mode and deployment (requires .env with LIFERAY_DEPLOYMENT_PATH):\n// Set environment variable: LIFERAY_DEPLOYMENT_PATH=/path/to/your/liferay/deploy\n// pnpm dev\n\n// To run a production build:\n// pnpm build","lang":"javascript","description":"Demonstrates `liferay-npm-bundler-improved` setup in `package.json` scripts, including development with watch/deploy mode and a production build incorporating source and asset copying. Requires Vite for watch mode."},"warnings":[{"fix":"Remove `lnbs-copy-sources` and `lnbs-copy-assets` from your build scripts and instead add `--copy-sources` and `--copy-assets` directly to your `liferay-npm-bundler-improved` command.","message":"The separate `lnbs-copy-sources` and `lnbs-copy-assets` commands from the original liferay-npm-bundler are removed. Their functionality is now integrated as direct CLI flags (`--copy-sources` and `--copy-assets`) on the `liferay-npm-bundler-improved` command.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your project utilizes `vite` for bundling if you intend to use the watch mode. Consider bundle size for optimal watch mode performance.","message":"The `--watch` mode (live instance replacement) currently functions exclusively when `vite` is used as the underlying build tool for your project. Performance may also degrade for very large bundles (build times exceeding 10 seconds).","severity":"gotcha","affected_versions":">=1.5.0-beta.1"},{"fix":"Define the `LIFERAY_DEPLOYMENT_PATH` environment variable in your shell or a `.env` file, pointing to your Liferay server's deployment directory, before running the deploy command.","message":"Enabling the deployment feature with `--deploy` or `-d` requires the `LIFERAY_DEPLOYMENT_PATH` environment variable to be explicitly set. If not set, an error will be thrown.","severity":"gotcha","affected_versions":">=1.5.0-beta.2"},{"fix":"Be aware of these limitations. For dynamic or global localization, manual approaches or alternative Liferay-native localization methods may still be necessary.","message":"The experimental localization support for `Liferay.Language.get('key')` functions only uses the default language configured in Liferay and processes `Language.properties` files defined within the portlet itself. It does not dynamically adapt to the user's current Liferay language or utilize global language properties.","severity":"gotcha","affected_versions":">=1.5.0-beta.4"},{"fix":"Developers requiring these specific features may need to maintain manual solutions or consider the official Liferay NPM Bundler for full compatibility, understanding the performance trade-offs.","message":"Key features such as package deduplication and full system configuration support are not currently implemented and are not planned for future development due to potential impact on speed or perceived low usage.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your `package.json` contains all necessary fields and that they are correctly formatted according to npm standards.","cause":"A required key, such as 'name' or 'version', is missing or malformed in your project's `package.json` file.","error":"Error: Missing key in package.json"},{"fix":"Ensure that the entry file specified in your `package.json` (or the default expected path) exists and is accessible.","cause":"The bundler could not locate the main entry file (e.g., `src/index.js` or specified in `main` field) for your portlet bundle.","error":"Error: Missing entry file"},{"fix":"Set the `LIFERAY_DEPLOYMENT_PATH` environment variable to the absolute path of your Liferay server's deployment folder (e.g., `LIFERAY_DEPLOYMENT_PATH=/opt/liferay/deploy`) before running the build command with deployment enabled.","cause":"The `--deploy` or `-d` flag was used without defining the `LIFERAY_DEPLOYMENT_PATH` environment variable, which specifies the target deployment directory.","error":"Error: LIFERAY_DEPLOYMENT_PATH environment variable not set. Please set the environment variable."}],"ecosystem":"npm"}