{"id":13444,"library":"liferay-npm-build-support","title":"Liferay NPM Build Support","description":"liferay-npm-build-support is a core utility library within the Liferay frontend ecosystem, providing essential scripts, loaders, and helpers for Liferay JS Toolkit projects. It orchestrates various build processes including compilation, linting, and asset management for Liferay portlets, themes, and other frontend modules. Currently at version 2.32.2, this package is part of a larger monorepo (`liferay-frontend-projects`) that sees frequent updates across its sub-packages, indicating an active development and maintenance cycle. Its primary differentiation lies in its tight integration with Liferay Portal's module architecture (e.g., OSGi fragments) and its tailored support for specific Liferay development patterns, such as handling module aliases and theme compilation, offering a streamlined development experience for Liferay developers.","status":"active","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-build-support","lang":"bash","label":"npm"},{"cmd":"yarn add liferay-npm-build-support","lang":"bash","label":"yarn"},{"cmd":"pnpm add liferay-npm-build-support","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides foundational utilities and CLI for Liferay frontend projects; liferay-npm-build-support often serves as a backend for its operations.","package":"liferay-js-toolkit","optional":false},{"reason":"Often used in conjunction for standardized build tasks in Liferay projects, building upon the support provided here.","package":"liferay-npm-scripts","optional":true},{"reason":"For Liferay theme development, this package's loaders and scripts underpin theme-specific build processes.","package":"liferay-theme-tasks","optional":true}],"imports":[{"note":"This package primarily exposes build configurations and loaders. Direct programmatic imports like this are less common, as functionality is often consumed via CLI or integrated build processes. This is an illustrative example for a hypothetical webpack configuration helper.","wrong":"const LiferayWebpackConfig = require('liferay-npm-build-support/webpack-config');","symbol":"LiferayWebpackConfig","correct":"import LiferayWebpackConfig from 'liferay-npm-build-support/webpack-config';"},{"note":"A hypothetical named export for a custom SASS loader, typically used within Webpack configurations (e.g., `module.rules`). Direct import into application code is rare, as usage is usually indirect via configuration.","symbol":"LiferaySassLoader","correct":"import { liferaySassLoader } from 'liferay-npm-build-support/loaders';"},{"note":"Illustrative example for a module exporting general build utility functions. Actual paths and exports would depend on the specific internals of the package, which are often not designed for public programmatic consumption.","symbol":"BuildUtils","correct":"import * as BuildUtils from 'liferay-npm-build-support/utils';"}],"quickstart":{"code":"{\n  \"name\": \"my-liferay-module\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A sample Liferay module using build support\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"build\": \"liferay-npm-scripts build\",\n    \"deploy\": \"liferay-npm-scripts deploy\",\n    \"start\": \"liferay-npm-scripts start\",\n    \"test\": \"liferay-npm-scripts test\"\n  },\n  \"devDependencies\": {\n    \"liferay-npm-build-support\": \"^2.32.0\",\n    \"liferay-npm-scripts\": \"^51.0.0\"\n  }\n}","lang":"json","description":"Demonstrates a typical `package.json` configuration for a Liferay module, using `liferay-npm-build-support` as a `devDependency` and leveraging `liferay-npm-scripts` (which internally uses `liferay-npm-build-support`) to run standard build, deploy, start, and test commands for Liferay projects."},"warnings":[{"fix":"Ensure you are developing for a Liferay Portal environment and follow Liferay's official project generation and build guidelines. Use Liferay's project templates to ensure correct setup.","message":"This package is part of the Liferay frontend ecosystem and is primarily designed to work with Liferay Portal. Its utilities, scripts, and loaders are highly tailored to Liferay's module structure, OSGi environment, and specific tooling (like Liferay JS Toolkit). Attempting to use it outside of a Liferay context is generally not recommended and will likely lead to compatibility issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the `liferay-frontend-projects` changelog and Liferay's official documentation for supported Node.js versions. Always update `liferay-npm-build-support` and `liferay-npm-scripts` to the latest compatible versions when upgrading your Node.js runtime.","message":"Updates to Node.js versions often require corresponding updates in Liferay's build tooling. For instance, recent versions introduced explicit support for Node.js v20. Older versions of `liferay-npm-build-support` (and related `npm-scripts`) may not be fully compatible with newer Node.js runtimes, potentially causing build failures or unexpected behavior.","severity":"breaking","affected_versions":"<51.2.0 (for liferay-npm-scripts sub-package context)"},{"fix":"Review module configurations and ensure they correctly declare their OSGi fragment status if applicable. Consult Liferay's module development documentation for proper configuration.","message":"The `liferay-npm-build-support` package, particularly through `liferay-npm-scripts`, handles OSGi fragment detection. Incorrectly configured modules might be erroneously identified as OSGi fragments, leading to build abortion in newer versions, where previously they might have passed with warnings or silent issues.","severity":"gotcha","affected_versions":">=51.0.0 (for liferay-npm-scripts sub-package context)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Align your project's Webpack version with the one expected by `liferay-npm-build-support` and `liferay-npm-scripts`. Often, the easiest fix is to rely solely on the versions managed by Liferay's tooling.","cause":"Webpack version incompatibility. Liferay's build tools are tightly coupled to specific Webpack versions, and direct upgrades or differing versions in a project's dependency tree can cause conflicts.","error":"Error: Cannot find module 'webpack/lib/ModuleFilenameHelpers'"},{"fix":"Ensure `node-sass` is installed as a `devDependency` (e.g., `npm install node-sass --save-dev`). Check `node-sass` compatibility matrix for your Node.js version, or consider using `sass` (Dart Sass) if supported by your Liferay build environment, as some versions of `npm-scripts` allow disabling `sass` via flags.","cause":"Missing `node-sass` dependency or incompatibility with Node.js version. `node-sass` can be notoriously sensitive to Node.js version changes.","error":"Error: Node Sass compiler not found. Please install node-sass."},{"fix":"Update `liferay-npm-build-support` (specifically `liferay-js-toolkit` sub-package context) to version `2.32.0` or newer, which includes a fix for this specific module alias resolution problem. Ensure your `package.json` specifies compatible versions.","cause":"Older versions of the build support had issues resolving relative module aliases or paths, particularly when they started with a dot, leading to module resolution failures.","error":"Error: `Module aliases that start with '.' are not handled correctly` (or similar resolution errors)"}],"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}