Minifying JavaScript and CSS to Optimize Liferay Theme Performance

A large number of JavaScript and CSS files can significantly impact a website's performance. When your Web pages rely on numerous or bulky JavaScript and CSS files, it can slow down page load times, consume excessive memory, and make the portal less responsive to user interactions. This can lead to frustration for users and degrade the overall experience.

To address this, you can minify these JavaScript and CSS files at build time, which reduces file size, improves page load speed, improved portal responsiveness, and an overall better user experience. Minification involves making the code compact while retaining functionality.

In newer versions of Liferay, the minifier.enable portal property is now deprecated. Previously, this property allowed CSS and JavaScript files to be minified at runtime. However, minifying resources during the build process is more efficient. This change enhances performance by eliminating the overhead runtime minification, leading to faster page loads and a smoother user experience.

In this blog, we will explore three different approaches to minifying JavaScript files in a Liferay theme. These methods are demonstrated in the context of a Gradle-based Liferay theme. However, the steps can also be adapted for themes created using Maven or the Liferay Theme Generator.

Prerequisites

• Basic knowledge of Liferay Theme
• Liferay DXP/Portal
• An IDE like Liferay Developer Studio, Eclipse, or IntelliJ IDEA
• A Liferay Workspace setup

Steps to Create and Minify JavaScript for a Liferay Theme

To improve the performance of a theme, it is essential to minify JavaScript files in Liferay. Minifying JavaScript reduces file sizes by removing unnecessary characters, thus enhancing page load times and reducing bandwidth usage. There are three different ways to achieve JavaScript minification in a Liferay theme:

1. Minify JavaScript with Gradle task and NPX command
2. Custom Minification with Node and UglifyJS
3. Using Gulp and gulp-uglify for Minification

Creating a Liferay Theme

Before minifying JavaScript, the first step is to create a theme using the command line. Use the following command to create a theme:

blade create -t theme minify-theme

This command generates the basic theme structure in Gradle module:

src/ 
├── main/ 
│   ├── resources/ 
│   │   └── resources-importer/ 
│   │       └── sitemap.json 
│   └── webapp/ 
│       ├── css/ 
│       │   └── _custom.scss 
│       └── WEB-INF/ 
│           ├── liferay-plugin-package.properties 
│           └── liferay-look-and-feel.xml

After creating the theme, customize it as required by adding JavaScript files and other assets.

Minify JavaScript Files in Liferay

Minifying JavaScript reduces file size by removing unnecessary characters, improving page load times and reducing bandwidth usage. Here are three methods to minify JavaScript files in your theme.

Method 1: Minify JavaScript with Gradle and NPX Command

1. To integrate JavaScript minification into the build process, you can add a custom Gradle task. This task uses npx and uglify-js to minify JavaScript files before the WAR file is created.
2. Node.jsand NPM must be installed.
3. Install uglify-js using npm:

   npm install –g uglify-js

4. Add a Custom Task in build.gradle:

   task minifyJs(type: Exec) { 
       commandLine 'npx', 'uglifyjs', 'src/main/webapp/js/*.js', '-c', '-m', '-o', 'build/buildTheme/js/optimized.min.js', '--source-map', 'url=optimized.min.js.map' 
   } 
    
   tasks.named("war").configure { 
       dependsOn minifyJs 
   }

5. By setting dependsOn minifyJs, the minifyJs task ensures that JavaScript files are minified before the war task (which creates the WAR file) is executed.
6. Run the Build Command:

   The --info option in Gradle is used to view detailed logs during the build process. For example, to see detailed logs while running the tasks

   ./gradlew build --info 

7. This generates two files:
   • optimized.min.js: Minified JavaScript.
   • optimized.min.js.map: Source map for debugging.

When To Use

• If your theme has a small number of JavaScript files and you want a quick, straightforward minification process.
• Ideal for themes that don't require advanced configuration or customization.

Method 2: Custom Minification with Node and UglifyJS

1. This approach allows for programmatically minifying JavaScript files using Node.js and UglifyJS. It scans all files matching a specific pattern, minifies them into a single file, and generates a source map for debugging.
2. Node.js and npm are not required on your system. The com.liferay.node plugin handles installation.
3. Create src/minify.js:

   "use strict"; 
    
   let UglifyJS = require("uglify-js"); 
   const fs = require('fs'); 
   const path = require('path'); 
   const {glob} = require('glob'); 
    
   const minifyFilesConfig = 
     [ 
      {matchFiles: "src/main/webapp/js/**/*.js", outDir: "build/buildTheme/js", outFile: "optimized.min.js", outMap: "optimized.min.js.map"}, 
     ] 
    
   async function minifyFiles(matchFiles, outDir, outFile, outMap) { 
     console.log(`minifying for pattern: ${matchFiles}`); 
     let files = await glob(matchFiles); 
     let sortedFiles = files.sort(); 
     let codeMap = {}; 
     sortedFiles.map(file => { 
      let splitPath = file.split(path.sep); 
      let relativePath = splitPath.slice(4).join(path.sep); 
      let name = path.basename(file); 
      console.log(`name: ${name}, relative path: ${relativePath}`); 
      codeMap[relativePath] = fs.readFileSync(file, "utf8"); 
     }); 
     let result = UglifyJS.minify(codeMap, 
      { 
       sourceMap: { 
        filename: outFile, 
        url: outMap 
       }, 
      }); 
     if (result.error) { 
      console.log(`minifying error: ${result.error}`); 
      return 
     } 
     fs.writeFileSync(`${outDir}/${outFile}`, result.code); 
     fs.writeFileSync(`${outDir}/${outMap}`, result.map); 
     console.log("Minification complete for files:", files); 
   } 
    
   minifyFilesConfig.map(file => minifyFiles(file.matchFiles, file.outDir, file.outFile, file.outMap)); 

4. Add package.json to the module root:

   { 
     "name": "minify-theme", 
     "version": "1.0.0", 
     "scripts": { 
       "build": "node src/minify.js" 
     }, 
     "devDependencies": { 
       "glob": "11.0.0", 
       "uglify-js": "3.19.3" 
     } 
   } 

5. Add the following task to build.gradle:

   buildscript { 
   	dependencies { 
   		classpath group: "com.liferay", name: "com.liferay.gradle.plugins.node", version: "8.1.1" 
   	} 
    
   	repositories { 
   		maven { 
   			url "https://repository-cdn.liferay.com/nexus/content/groups/public" 
   		} 
   	} 
   } 
    
   apply plugin: "com.liferay.node" 
    
   tasks.named("war").configure { 
       dependsOn 'packageRunBuild' 
   } 
    

6. Gradle automatically generates a packageRun${script} task for each script in package.json using ExecutePackageManagerTask when the Liferay Node plugin is applied.
7. Run the Build Command:

   ./gradlew build

8. This generates two files:
   • optimized.min.js: Minified JavaScript.
   • optimized.min.js.map: Source map for debugging.

How It Works:

• This method programmatically scans and minifies all JavaScript files in your theme using Node and UglifyJS.
• Generates a single minified file and a source map.

When to Use:

• If your theme has a complex folder structure or you need fine-grained control over the minification process.
• Ideal for projects requiring custom logging or advanced configuration.

Method 3: Using Gulp and gulp-uglify for Minification

1. This method implements Gulp, a popular task runner, and gulp-uglify for JavaScript minification. It processes all JavaScript files in the build/buildTheme/js directory and outputs their minified versions in the same location.
2. Node.js and npm are not required on your system. The com.liferay.node plugin handles installation.
3. Create src/minify.js

   "use strict"; 
    
   var gulp = require("gulp"); 
   var log = require("fancy-log"); 
   var uglify = require("gulp-uglify"); 
    
   log("Minifying JavaScript files..."); 
   gulp.src("build/buildTheme/js/**/*.js") 
       .pipe(uglify()) 
       .on("error", error => log.error("Minification error:", error.toString())) 
       .pipe(gulp.dest("build/buildTheme/js")) 
       .on("end", () => log("Minification complete.")); 
    

4. Add package.json to the module root:

   { 
     "name": "minify-theme", 
     "version": "1.0.0", 
     "devDependencies": { 
       "gulp": "4.0.2", 
       "gulp-uglify" : "3.0.2", 
       "fancy-log" : "2.0.0" 
     }, 
     "scripts": { 
       "build": "node src/minify.js" 
     } 
   } 

5. Add the following task to build.gradle:

   buildscript { 
   	dependencies { 
   		classpath group: "com.liferay", name: "com.liferay.gradle.plugins.node", version: "8.1.1" 
   	} 
    
   	repositories { 
   		maven { 
   			url "https://repository-cdn.liferay.com/nexus/content/groups/public" 
   		} 
   	} 
   } 
    
   apply plugin: "com.liferay.node" 
    
   tasks.named("war").configure { 
       dependsOn 'packageRunBuild' 
   }

6. This method compresses all JavaScript files into their respective minified versions within the 'build/buildTheme/js' directory.

How It Works:

• Utilizes Gulp to process and minify JavaScript files.
• Logs errors and provides detailed progress updates.

When to Use:

• If you prefer Gulp's simplicity and flexibility for JavaScript processing.
• Suitable for developers familiar with Gulp and its ecosystem.

How to Use and import this minified JS

• After minifying your JavaScript, you'll need to include it in your theme. In your FreeMarker template (init_custom.ftl or portal_normal.ftl), add the following code:

  <#-- Import the minified JavaScript file --> 
  <script type="text/javascript" src="${javascript_folder}/optimized.min.js"/>

• This will load your minified JavaScript file correctly from the js directory of your theme.

Steps to Minify CSS for a Liferay Theme

Minifying CSS improves performance by reducing file size and load times. Below are the steps to create and minify CSS in a Liferay theme.

Minify CSS Files in Liferay

1. To integrate CSS minification into the build process, you can add a custom Gradle task. This task uses npx and uglify-js to minify CSS files before the WAR file is created.
2. Node.js and npm are not required on your system. The com.liferay.node plugin handles installation.
3. Add following dependency, plugin and Custom Task in build.gradle:

   buildscript {  
       dependencies {  
           classpath group: "com.liferay", name: "com.liferay.gradle.plugins.node", version: "8.1.1" 
       }  
       repositories {  
           maven {  
               url "https://repository-cdn.liferay.com/nexus/content/groups/public"  
           }  
       }
   }  
   
   apply plugin: "com.liferay.node"  
   
   tasks.named("war").configure {  
       dependsOn 'packageRunBuild'  
   } 

4. Add package.json to the module root:

   { 
     "name": "minify-theme", 
     "version": "1.0.0", 
     "scripts": { 
       "build": "cleancss --batch --batch-suffix '.min' build/buildTheme/css/*.css" 
     }, 
     "devDependencies": { 
       "clean-css-cli": "5.6.3" 
     }
   } 

5. This compresses all css files into their respective minified versions within the 'build/buildTheme/css' directory.

How It Works:

• Uses cleancss to process and minify CSS files.
• The --batch option minifies multiple CSS files at once.
• The --batch-suffix '.min' adds .min to the output files to distinguish them from the original files.

When to Use:

• If you prefer a lightweight and straightforward approach to CSS minification.
• Suitable for developers who need to quickly minify CSS files in a project without setting up a complex build process.
• Ideal for simple CSS optimization tasks with minimal configuration.

Conclusion

Minifying JavaScript and CSS files is a crucial step in Liferay Theme Development to optimize portal performance. By reducing the size of these files, you can achieve faster page load times, improved resource efficiency, and an enhanced user experience. This blog explores various methods, including Gradle tasks, Node.js scripts, and Gulp pipelines, providing flexible solutions for different development workflows. Additionally, these techniques can be seamlessly adapted for Maven-based projects or those using the Liferay Theme Generator with minimal modifications. Choose the approach that best fits your Liferay Theme Development process and create a high-performance, optimized Liferay portal.