{"id":15678,"library":"liferay-npm-bundler-plugin-exclude-imports","title":"Liferay NPM Bundler Plugin: Exclude Imports","description":"liferay-npm-bundler-plugin-exclude-imports is a plugin designed for the liferay-npm-bundler tool, currently at version 2.32.2. Its core function is to allow developers to explicitly exclude specific imported dependencies from the final JavaScript bundle generated for Liferay DXP projects. This is critical for managing bundle sizes and leveraging Liferay's OSGi module runtime, where certain dependencies might be provided globally or by other deployed modules, preventing duplication. While it facilitates fine-grained control over bundling, the liferay-npm-bundler itself, and by extension this plugin, has been officially deprecated as of Liferay 2024 Q4/Portal GA129, with plans for future removal in favor of standard JavaScript tooling like Esbuild, Webpack, or Vite. Releases are part of the broader liferay-frontend-projects monorepo, suggesting its lifecycle is tied to the evolution of Liferay's frontend tooling, although this specific package does not have frequent individual releases. It's a key tool for legacy Liferay DXP projects requiring fine-grained control over OSGi-compliant module bundling.","status":"deprecated","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-bundler-plugin-exclude-imports","lang":"bash","label":"npm"},{"cmd":"yarn add liferay-npm-bundler-plugin-exclude-imports","lang":"bash","label":"yarn"},{"cmd":"pnpm add liferay-npm-bundler-plugin-exclude-imports","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin specifically designed to extend the functionality of liferay-npm-bundler. It is a peer dependency.","package":"liferay-npm-bundler","optional":false}],"imports":[{"note":"This plugin is primarily configured via a string reference ('exclude-imports') within the `.npmbundlerrc` file. Direct programmatic import of its main export (e.g., a plugin class or factory function) is less common for end-users, but might be used when customizing the bundler's internal plugin loading or for testing.","wrong":"import { ExcludeImportsPlugin } from 'liferay-npm-bundler-plugin-exclude-imports';","symbol":"ExcludeImportsPlugin","correct":"import ExcludeImportsPlugin from 'liferay-npm-bundler-plugin-exclude-imports';"},{"note":"CommonJS `require` syntax for environments that do not support ESM or for legacy custom bundler scripts. While modern Liferay frontend projects often use ESM, `require` might still be encountered in some contexts. The bundler itself loads plugins internally by name resolution, making direct `require` by end-users rare.","symbol":"ExcludeImportsPlugin","correct":"const ExcludeImportsPlugin = require('liferay-npm-bundler-plugin-exclude-imports');"},{"note":"For TypeScript users who might need to type a plugin instance if interacting with it programmatically. This assumes the package provides a corresponding type definition for its primary export.","wrong":"import { ExcludeImportsPluginType } from 'liferay-npm-bundler-plugin-exclude-imports';","symbol":"ExcludeImportsPluginType","correct":"import type { ExcludeImportsPluginType } from 'liferay-npm-bundler-plugin-exclude-imports';"}],"quickstart":{"code":"{\n  \"*\": {\n    \"plugins\": [\n      \"exclude-imports\"\n    ],\n    \"config\": {\n      \"exclude-imports\": {\n        \"excludedPackages\": [\n          \"some-common-utility\",\n          \"@liferay/some-portal-api\"\n        ]\n      }\n    }\n  },\n  \"my-custom-module\": {\n    \"plugins\": [\n      \"exclude-imports\"\n    ],\n    \"config\": {\n      \"exclude-imports\": {\n        \"excludedPackages\": [\n          \"react\",\n          \"react-dom\"\n        ]\n      }\n    }\n  }\n}","lang":"json","description":"Demonstrates how to configure the plugin in a Liferay project's `.npmbundlerrc` file to exclude specific dependencies like 'some-common-utility' or 'react' from being bundled for either all modules or a specific module, leveraging Liferay's OSGi runtime for provision. The `excludedPackages` property is a hypothetical common configuration option for such a plugin."},"warnings":[{"fix":"Migrate your Liferay frontend projects to use modern standard JavaScript bundlers like Esbuild, Webpack, or Vite. Consult Liferay's official migration guides for updated best practices on migrating away from the liferay-npm-bundler ecosystem.","message":"The underlying liferay-npm-bundler, for which this is a plugin, has been officially deprecated as of Liferay 2024 Q4/Portal GA129. It is planned for future removal. This means the plugin will become obsolete with the bundler's deprecation and eventual removal.","severity":"breaking","affected_versions":">=2.x"},{"fix":"Thoroughly verify that any excluded dependency is indeed available at runtime via Liferay's module system. Use Liferay's module debug tools to inspect available modules. Avoid excluding critical application dependencies unless explicitly instructed or certain of their external provision by the Liferay platform or other OSGi bundles.","message":"Incorrectly excluding a dependency that is not actually provided by the Liferay runtime or another OSGi module will lead to runtime errors (e.g., 'Module not found' or `undefined` references) in the browser. This plugin bypasses standard bundling, operating on the assumption that the excluded dependency is externally available.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Double-check `.npmbundlerrc` syntax and placement according to Liferay documentation for bundler plugins. If issues persist, enable `dump-report: true` in your `.npmbundlerrc` to generate a detailed HTML report for debugging the bundler's processing and plugin application.","message":"The liferay-npm-bundler's plugin loading mechanism can be sensitive to configuration. Ensure the plugin name ('exclude-imports') is correctly specified in your `.npmbundlerrc` file within the appropriate `plugins`, `pre-plugins`, or `post-plugins` section, and that any specific plugin options are correctly nested under a `config['exclude-imports']` object.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Review your `.npmbundlerrc` configuration and ensure 'some-dependency-name' is either removed from the exclusion list, or confirm that it is correctly provided by another OSGi bundle or the Liferay runtime. Inspect the generated OSGi bundle to verify its contents.","cause":"A dependency was excluded by the liferay-npm-bundler-plugin-exclude-imports plugin but is not available at runtime in the Liferay DXP environment.","error":"Module not found: Error: Can't resolve 'some-dependency-name' in 'path/to/your/module'"},{"fix":"Verify that `liferay-npm-bundler-plugin-exclude-imports` is correctly installed in your project's `node_modules`. Check for typos in the plugin name `\"exclude-imports\"` within your `.npmbundlerrc` file under the `plugins` array. Ensure the `.npmbundlerrc` file is valid JSON and correctly placed.","cause":"The liferay-npm-bundler could not locate or correctly instantiate the plugin, often due to a typo in the plugin name within `.npmbundlerrc` or an installation issue.","error":"LiferayNPMBundler: Plugin 'exclude-imports' not found or invalid."}],"ecosystem":"npm"}