Running an existing React app on Liferay DXP makes the app available as a widget for using on site pages. You can adapt your existing React app, but this doesn’t give you access to the bundler and its various loaders to develop your project further in Liferay DXP. To have access to all of Liferay DXP’s features, you must use the Liferay JS Generator and Liferay npm Bundler to merge your files into a portlet bundle, update your static resource paths, and deploy your bundle.
Figure 1: Apps like this Guestbook app are easy to migrate to Liferay DXP.
Follow these steps:
-
Using npm, install the Liferay JS Generator:
npm install -g yo generator-liferay-js
-
Generate a React based portlet bundle project for deploying your app to your Liferay DXP installation.
yo liferay-js
Select
React based portlet
and opt for generating sample code. Here’s the bundle’s structure:my-react-portlet-bundle
assets/
→ CSS and resourcescss/
→ CSS filesstyles.css
→ Default CSS file
features/
→ Liferay DXP bundle featureslocalization
→ Resource bundlesLanguage.properties
→ Default language keys
src/
→ JavaScript and React component filesAppComponent.js
→ Sample React component that you can removeindex.js
→ Main module used to initialize the portlet
.babelrc
→ Babel configuration.npmbuildrc
→ Build configuration.npmbundlerrc
→ Bundler configurationpackage.json
→ npm bundle configurationREADME.md
-
Copy your app files, matching the types listed below, into your new project.
File type Destination Comments CSS assets/css/
Overwrite styles.css
.JavaScript src/
Merge with all files except index.js
—the main module merge is explained in a later step.Static resources assets/
Include resources such as image files here -
Update your bundle to use portlet-level styling.
- Import all component CSS files through the CSS file (default is
styles.css
) your bundle’spackage.json
file sets for your portlet. Here’s the default setting:
"portlet": { "com.liferay.portlet.header-portlet-css": "/css/styles.css", ... }
- Remove any CSS imports you have in your JS files
- Import all component CSS files through the CSS file (default is
-
Update any static resource references to use the
web-context
value declared in your project’s.npmbundlerrc
file, and remove any imports for the resource. For example, if you have an image file calledlogo.png
in yourassets
folder, you would use the format below. Note that theassets
folder is not included in the path.Here is the format:
/o/[web-context]/[resource]
Here’s an example image resource:
<img alt="React logo" src="/o/react-guestbook-migrated/logo.png">
-
Merge your entry module with
src/index.js
, configuring it to dynamically load components.- Use the
HashRouter
for routing between component views, as Liferay DXP requires hash routing for proper portal navigation:
import { HashRouter as Router } from 'react-router-dom';
-
Place your code inside the
main()
function. -
Render your app inside the
portletElementId
element that is passed in themain()
function. This is required to render the React app inside the portlet.
Your entry module
index.js
should look like this.import React from 'react'; import ReactDOM from 'react-dom'; //import './index.css';//removed for Portal Migration import App from './App'; import { HashRouter as Router } from 'react-router-dom'; export default function main({portletNamespace, contextPath, portletElementId}) { ReactDOM.render(( <Router> <App/> </Router> ), document.getElementById(portletElementId)); }
- Use the
-
Merge your app
package.json
file’sdependencies
anddevDependencies
into the bundle’spackage.json
. -
Finally, deploy your bundle:
npm run deploy
Congratulations! Your React app is deployed and now available as a widget that you can add to site pages.
The Liferay npm Bundler confirms the deployment:
Report written to liferay-npm-bundler-report.html
Deployed my-react-guestbook-1.0.0.jar to c:\git\bundles
The Liferay DXP console confirms your bundle started:
2019-03-22 20:17:53.181 INFO
[fileinstall-C:/git/bundles/osgi/modules][BundleStartStopLogger:39]
STARTED my-react-guestbook_1.0.0 [1695]
To Find your widget, click the Add icon
(),
navigate to Widgets and then the category you specified to the Liferay Bundle
Generator (Sample is the default category).