Liferay NPM Bundler Isomorphic Preset

1.8.0 verified Thu Apr 23 auth: no javascript deprecated

This package, `liferay-npm-bundler-preset-isomorphic`, provides a specialized configuration preset for the `liferay-npm-bundler`, targeting JavaScript modules designed to run both in browser and server environments (isomorphic code) within a Liferay Portal context. It bundles `babel-preset-liferay-isomorphic` for Babel transformations and `liferay-npm-bundler-plugin-replace-browser-modules` to handle environment-specific module loading and aliasing. While version 1.8.0 is the current stable release for this preset, the underlying `liferay-npm-bundler` tool itself is officially deprecated as of Liferay 2024.Q4/Portal GA129 and is slated for removal, with Liferay shifting towards standard, non-Liferay-specific JavaScript tooling like `esbuild`. Its primary differentiator was simplifying complex Liferay-specific build configurations for isomorphic modules, but its relevance is now diminishing due to the deprecation of its core dependency.

Common errors

error Error: ENOENT: no such file or directory, open '...' ↓

cause This error during `liferay-npm-bundler` execution often indicates a file path resolution issue, commonly stemming from an incompatibility with updated transitive dependencies (e.g., `globby`) in older `liferay-npm-bundler` versions.

fix

Upgrade your liferay-npm-bundler dependency to version 2.32.1 or higher to resolve known globby compatibility problems.

error node:internal/fs/utils:344 throw err; ^ Error: ENOENT: no such file or directory, open '/var/jenkins_home/workspace/.../node_modules/lodash@4.17.21/minBy.js' ↓

cause This specific stack trace is a known manifestation of the `globby` transitive dependency issue affecting `liferay-npm-bundler` versions older than `2.32.1`, leading to incorrect file path lookups.

fix

Update liferay-npm-bundler to version 2.32.1 or a newer version to fix the underlying dependency incompatibility.

Warnings

breaking The `liferay-npm-bundler` tool, which this preset configures, is officially deprecated as of Liferay 2024.Q4/Portal GA129 and is slated for future removal. Liferay's recommended approach is to transition to standard JavaScript build tools like `esbuild` to manage module bundling. ↓

fix Plan and execute a migration of your build process away from `liferay-npm-bundler` and its associated presets to standard tooling (e.g., `esbuild`, Webpack).

breaking Older versions of `liferay-npm-bundler` (prior to 2.32.1) could encounter `ENOENT` errors during the build process due to unexpected breaking changes in transitive dependencies like `globby`. ↓

fix Update your `liferay-npm-bundler` dependency to version `2.32.1` or newer to ensure compatibility and resolve transitive dependency issues.

gotcha The `liferay-npm-bundler-plugin-replace-browser-modules` (a plugin utilized by this preset) changed its default `resolve.aliasFields` behavior. It previously scanned `unpkg` and `jsdelivr` fields in `package.json`, which caused problems and is no longer supported. The default now strictly uses `['browser']`. Custom configurations or `package.json` entries relying on `unpkg` or `jsdelivr` for aliasing may cease to function as expected. ↓

fix Ensure your `package.json` uses the `browser` field for aliasing isomorphic modules and migrate away from relying on `unpkg` or `jsdelivr` fields for this specific purpose.

Install

npm install liferay-npm-bundler-preset-isomorphic

yarn add liferay-npm-bundler-preset-isomorphic

pnpm add liferay-npm-bundler-preset-isomorphic

Imports

preset config
wrong
```
import LiferayIsomorphicPreset from 'liferay-npm-bundler-preset-isomorphic'
```
correct
```
{
    "preset": "liferay-npm-bundler-preset-isomorphic"
}
```
This package is a configuration preset, not a JavaScript module. Its 'usage' is by referencing its name within the `preset` field of your project's `.npmbundlerrc` file. It does not export any symbols for direct `import` or `require`.
configuration reference
wrong
```
const isomorphicConfig = require('liferay-npm-bundler-preset-isomorphic');
```
correct
```
// Add to .npmbundlerrc: {
//     "preset": "liferay-npm-bundler-preset-isomorphic"
// }
```
It is a common mistake to attempt to import or require bundler presets as if they were runtime libraries. This package serves as a declarative configuration for the `liferay-npm-bundler` and has no programmatic API.
no direct code usage
wrong
```
import { IsomorphicPreset } from 'liferay-npm-bundler-preset-isomorphic';
```
correct
```
// This package is used exclusively via .npmbundlerrc configuration.
```
Developers should consult the Liferay npm Bundler documentation for how to configure and extend presets, rather than looking for JavaScript exports from this package.

Quickstart

Demonstrates how to install the preset and configure it in the `.npmbundlerrc` file for use with `liferay-npm-bundler`.

npm install --save-dev liferay-npm-bundler-preset-isomorphic

// Create or update your .npmbundlerrc file in your project root:
// .npmbundlerrc
{
    "preset": "liferay-npm-bundler-preset-isomorphic"
}

// Then run the liferay-npm-bundler as part of your build process (e.g., in package.json scripts):
// package.json
// {
//   "scripts": {
//     "build": "liferay-npm-bundler"
//   }
// }