Liferay npm Bundler Plugin for Create React App

Common errors

• Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause This error typically indicates that multiple instances of React are being loaded into the application. This often occurs when using `yarn` as a package manager, especially with UI libraries like Material UI, which can lead to duplicate React installations.
  fix Switch your project's package manager from `yarn` to `npm`. Delete your `node_modules` directory and `package-lock.json` (if present), then run `npm install` to ensure a single, consistent React installation.

• Error: ENOENT: no such file or directory, stat '.../build/static/css/main.<hash>.css'

  cause The `liferay-npm-bundler-plugin-create-react-app` plugin, or related bundler processes, expects a bundled CSS file to be present in the Create React App `build/static/css` output directory. This error occurs if no CSS file is generated by CRA because your project's entry point (e.g., `index.js`) does not contain an `import` statement for a stylesheet.
  fix Ensure that your Create React App project's main entry point, typically `src/index.js`, includes an explicit import statement for a CSS file (e.g., `import './index.css';`). This will trigger CRA to generate the expected CSS bundle that the Liferay bundler plugin anticipates.

Warnings

• breaking The underlying `liferay-npm-bundler` tool, which this plugin extends, is deprecated as of Liferay 2024.Q4 (Portal GA129) and is slated for future removal. New Liferay DXP projects should consider migrating to Client Extensions and modern build tools like Vite, as the `liferay-npm-bundler` ecosystem is no longer actively developed for new features.
  Fix: For new projects or migration, consult Liferay's official documentation on Client Extensions and modern front-end development practices. For existing projects, be aware that active support for this bundling approach may cease in future Liferay versions. Plan for migration.
• gotcha When developing Create React App projects for Liferay, strict adherence to `npm` for package management is often required. Using `yarn` (especially with UI libraries like Material UI) can lead to 'Invariant Violation: Invalid hook call' errors due to duplicate React instances being bundled.
  Fix: Always use `npm` as your package manager when developing Liferay React applications to avoid potential bundling conflicts and runtime errors with React hooks. Delete `node_modules` and `package-lock.json`, then reinstall with `npm install`.
• gotcha Create React App projects might fail to bundle correctly if the main `index.js` file does not explicitly import a CSS file (e.g., `import './index.css';`). The plugin's internal logic may assume the presence of a `static/css` directory in the build output, which might be missing otherwise.
  Fix: Ensure that your `index.js` (or primary entry point) explicitly imports at least one CSS file, even if it's an empty one, to satisfy the plugin's expectations and generate the necessary static CSS output.
• gotcha Compatibility issues can arise with different React versions and JSX runtimes. Liferay has historically used React 16 with a Classic JSX runtime. Using React 18 or configuring an 'automatic' JSX runtime in your CRA project might require specific configurations or adjustments to avoid conflicts with Liferay's embedded React instances.
  Fix: Align your project's React version and JSX runtime configuration with Liferay's recommendations for your specific DXP version. If using newer React versions, carefully manage externalized dependencies and consider Liferay Client Extensions for more isolated and independent bundling.

Install

• npm install liferay-npm-bundler-plugin-create-react-app npm
• yarn add liferay-npm-bundler-plugin-create-react-app yarn
• pnpm add liferay-npm-bundler-plugin-create-react-app pnpm

Imports

• Liferay npm Bundler Plugin Configuration
  wrong:

  import { createReactAppPlugin } from 'liferay-npm-bundler-plugin-create-react-app';

  correct:

  /* In .npmbundlerrc */
  {
    "*": {
      "plugins": [
        "create-react-app"
      ]
    }
  }

  This package is a build-time plugin configured in the `.npmbundlerrc` file, not a JavaScript module for runtime import. The plugin name 'create-react-app' (without the full prefix) is commonly used within the `plugins` array. Alternatively, for a more comprehensive setup, the `liferay-npm-bundler-preset-create-react-app` preset (e.g., `"preset": "liferay-npm-bundler-preset-create-react-app"`) is often preferred and internally leverages this plugin.

Quickstart

Demonstrates how to enable the `create-react-app` plugin in a `.npmbundlerrc` file for Liferay's npm bundler to process a Create React App project.

{
  "//": "This .npmbundlerrc file configures the Liferay npm Bundler for a Create React App project.",
  "//": "It activates the 'create-react-app' plugin to handle CRA-specific build adjustments.",
  "*": { "plugins": [ "create-react-app" ] },
  "//": "For a comprehensive setup, the 'liferay-npm-bundler-preset-create-react-app' preset is often preferred:",
  "//": "{\n  \"preset\": \"liferay-npm-bundler-preset-create-react-app\"\n}",
  "//": "This example assumes a standard Create React App project structure.",
  "//": "Ensure your package.json name is unique and follows Liferay's naming conventions for client extensions.",
  "//": "To build, navigate to your project root and run: npx liferay-npm-bundler"
}