Adapting Existing Apps to Run on Liferay DXP

There are two ways to get your existing front-end applications running on Liferay DXP:

1. Migrate your project to a Liferay JS Toolkit project.

2. Since v2.15.0 of the Liferay JS Toolkit, create projects normally, as you would with create-react-app, Angular CLI (any project containing @angular/cli as a dependency or devDependency), and Vue CLI (any project containing @vue/cli-service as a dependency or devDependency), and adapt them to run on Liferay DXP.

Only adapt your project if you intend it to be platform-agnostic. If you want to integrate with Liferay DXP fully and have access to all the features and benefits that it provides, migrate your project to a true Liferay JS Toolkit project instead.

The reason for this is some of Liferay DXP’s features may not be available because the native frameworks expect certain things. For example, Angular assumes that it controls a whole Single Page Application as opposed to the small portion of the page that it controls in a portlet-based platform such as Liferay DXP. Since webpack bundles all JavaScript in a single file to consume per app, if there are five widgets on a page, you have five copies of the framework in the JavaScript interpreter. To prevent this, migrate your project to a true Liferay JS Toolkit project instead.

To adapt your project, it must have the structure shown below:

• Angular CLI projects must use app-root as the application’s Dom selector.

• creact-react-app projects must use ReactDom.render() call in your entry point with a document.getElementById() parameter.

• Vue CLI projects must use #app as the application’s DOM selector.

When your project meets the requirements, you can follow these steps to use the Liferay JS Generator to adapt it:

1. Open the command line and navigate to your project’s folder.

2. Run the Liferay JS Generator’s adapt subtarget:

   yo liferay-js:adapt
   

   

   Figure 1: You can run the adapt subtarget of the Liferay JS Generator to adapt your existing apps for Liferay.

3. Answer the prompts. An example configuration appears below:

   ? Under which category should your widget be listed? category.sample
   ? Do you have a local installation of Liferay for development? Yes
   ? Where is your local installation of Liferay placed? /home/user/liferay
   

   Your project is adapted to use the Liferay JS Toolkit and run on Liferay DXP!

   

   Figure 2: You can run the adapt subtarget of the Liferay JS Generator to adapt your existing apps for Liferay.

4. The adapt process automatically adds a few npm scripts to the project’s package.json so you can build and deploy your project to Liferay DXP. Note that you can swap npm for yarn below if you prefer to use yarn instead.

   Run the command below to add a deployable JAR to the build.liferay folder in your project. For example, if you want to build the JAR and copy it to another app server, you can run this command:

   npm run build:liferay
   

   Run the command below to deploy the adapted app to your Liferay DXP instance:

   npm run deploy:liferay
   

Great! Now you know how to use the Liferay JS Generator to adapt your existing apps to run on Liferay DXP. See the React Guestbook App for a working example of an adapted app.

Figure 3: Your adapted app runs in Liferay in no time.