Liferay NPM Bundler Improved

1.5.1 · active · verified Sun Apr 19

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.

Common errors

```
Error: Missing key in package.json
```
cause A required key, such as 'name' or 'version', is missing or malformed in your project's `package.json` file.

fix Verify that your `package.json` contains all necessary fields and that they are correctly formatted according to npm standards.
```
Error: Missing entry file
```
cause The bundler could not locate the main entry file (e.g., `src/index.js` or specified in `main` field) for your portlet bundle.

fix Ensure that the entry file specified in your `package.json` (or the default expected path) exists and is accessible.
```
Error: LIFERAY_DEPLOYMENT_PATH environment variable not set. Please set the environment variable.
```
cause The `--deploy` or `-d` flag was used without defining the `LIFERAY_DEPLOYMENT_PATH` environment variable, which specifies the target deployment directory.

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.

Warnings

breaking 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.
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.
gotcha 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).
Fix: Ensure your project utilizes `vite` for bundling if you intend to use the watch mode. Consider bundle size for optimal watch mode performance.
gotcha 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.
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.
gotcha 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.
Fix: Be aware of these limitations. For dynamic or global localization, manual approaches or alternative Liferay-native localization methods may still be necessary.
gotcha 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.
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.

Install

npm install liferay-npm-bundler-improved npm
yarn add liferay-npm-bundler-improved yarn
pnpm add liferay-npm-bundler-improved pnpm

Imports

liferay-npm-bundler-improved
wrong:
```
import * as bundler from 'liferay-npm-bundler-improved'
```
correct:
```
npx liferay-npm-bundler-improved [options]
```
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.
WatchMode
wrong:
```
import { enableWatchMode } from 'liferay-npm-bundler-improved'
```
correct:
```
liferay-npm-bundler-improved --watch
```
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.
Deployment
wrong:
```
import { deployPortlet } from 'liferay-npm-bundler-improved'
```
correct:
```
liferay-npm-bundler-improved --deploy
```
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.

Quickstart

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.

{
  "name": "my-liferay-portlet",
  "version": "1.0.0",
  "description": "A sample Liferay portlet using liferay-npm-bundler-improved.",
  "main": "src/index.js",
  "scripts": {
    "dev": "liferay-npm-bundler-improved -w --deploy",
    "build": "liferay-npm-bundler-improved --copy-sources --copy-assets"
  },
  "keywords": ["liferay", "portlet"],
  "devDependencies": {
    "liferay-npm-bundler-improved": "^1.5.1",
    "vite": "^5.0.0" // Required for watch mode
  },
  "license": "MIT"
}

// To install dependencies:
// pnpm i --D liferay-npm-bundler-improved vite

// To use in development with watch mode and deployment (requires .env with LIFERAY_DEPLOYMENT_PATH):
// Set environment variable: LIFERAY_DEPLOYMENT_PATH=/path/to/your/liferay/deploy
// pnpm dev

// To run a production build:
// pnpm build

view raw JSON →