{"id":15680,"library":"liferay-npm-bundler-plugin-create-react-app","title":"Liferay npm Bundler Plugin for Create React App","description":"The `liferay-npm-bundler-plugin-create-react-app` is a specialized plugin designed to facilitate the integration of projects bootstrapped with Create React App (CRA) into the Liferay Portal environment. It works in conjunction with `liferay-npm-bundler` to transform standard CRA output into OSGi bundles, making them deployable as Liferay widgets or portlets. This plugin manages the necessary adaptations for module loading, asset paths, and other build configurations specific to Liferay's ecosystem, which typically relies on an AMD loader. While the current stable version is 2.14.1, the underlying `liferay-npm-bundler` toolset is deprecated as of Liferay 2024.Q4 (Portal GA129) and is planned for future removal, meaning this plugin is primarily relevant for older Liferay DXP/Portal versions. Its key differentiator is simplifying the process of making CRA projects compatible with Liferay's unique bundling requirements without extensive manual configuration.","status":"deprecated","version":"2.14.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install liferay-npm-bundler-plugin-create-react-app","lang":"bash","label":"npm"},{"cmd":"yarn add liferay-npm-bundler-plugin-create-react-app","lang":"bash","label":"yarn"},{"cmd":"pnpm add liferay-npm-bundler-plugin-create-react-app","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for liferay-npm-bundler, which orchestrates the bundling process. It is a mandatory peer dependency for this plugin to function.","package":"liferay-npm-bundler","optional":false},{"reason":"Required as a core dependency for Create React App projects which this plugin targets for bundling into Liferay.","package":"react","optional":false},{"reason":"Required as a core dependency for Create React App projects to render components, which this plugin prepares for Liferay deployment.","package":"react-dom","optional":false}],"imports":[{"note":"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.","wrong":"import { createReactAppPlugin } from 'liferay-npm-bundler-plugin-create-react-app';","symbol":"Liferay npm Bundler Plugin Configuration","correct":"/* In .npmbundlerrc */\n{\n  \"*\": {\n    \"plugins\": [\n      \"create-react-app\"\n    ]\n  }\n}"}],"quickstart":{"code":"{\n  \"//\": \"This .npmbundlerrc file configures the Liferay npm Bundler for a Create React App project.\",\n  \"//\": \"It activates the 'create-react-app' plugin to handle CRA-specific build adjustments.\",\n  \"*\": { \"plugins\": [ \"create-react-app\" ] },\n  \"//\": \"For a comprehensive setup, the 'liferay-npm-bundler-preset-create-react-app' preset is often preferred:\",\n  \"//\": \"{\\n  \\\"preset\\\": \\\"liferay-npm-bundler-preset-create-react-app\\\"\\n}\",\n  \"//\": \"This example assumes a standard Create React App project structure.\",\n  \"//\": \"Ensure your package.json name is unique and follows Liferay's naming conventions for client extensions.\",\n  \"//\": \"To build, navigate to your project root and run: npx liferay-npm-bundler\"\n}","lang":"json","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Invariant Violation: Invalid hook call. Hooks can only be called inside of the body of a function component."},{"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.","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.","error":"Error: ENOENT: no such file or directory, stat '.../build/static/css/main.<hash>.css'"}],"ecosystem":"npm"}