Liferay NPM Bundler Plugin: Exclude Imports

Common errors

• Module not found: Error: Can't resolve 'some-dependency-name' in 'path/to/your/module'

  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.
  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.

• LiferayNPMBundler: Plugin 'exclude-imports' not found or invalid.

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install liferay-npm-bundler-plugin-exclude-imports npm
• yarn add liferay-npm-bundler-plugin-exclude-imports yarn
• pnpm add liferay-npm-bundler-plugin-exclude-imports pnpm

Imports

• ExcludeImportsPlugin
  wrong:

  import { ExcludeImportsPlugin } from 'liferay-npm-bundler-plugin-exclude-imports';

  correct:

  import ExcludeImportsPlugin from 'liferay-npm-bundler-plugin-exclude-imports';

  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.
• ExcludeImportsPlugin

  const ExcludeImportsPlugin = require('liferay-npm-bundler-plugin-exclude-imports');

  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.
• ExcludeImportsPluginType
  wrong:

  import { ExcludeImportsPluginType } from 'liferay-npm-bundler-plugin-exclude-imports';

  correct:

  import type { ExcludeImportsPluginType } from 'liferay-npm-bundler-plugin-exclude-imports';

  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.

Quickstart

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.

{
  "*": {
    "plugins": [
      "exclude-imports"
    ],
    "config": {
      "exclude-imports": {
        "excludedPackages": [
          "some-common-utility",
          "@liferay/some-portal-api"
        ]
      }
    }
  },
  "my-custom-module": {
    "plugins": [
      "exclude-imports"
    ],
    "config": {
      "exclude-imports": {
        "excludedPackages": [
          "react",
          "react-dom"
        ]
      }
    }
  }
}