March 29, 2023

Unveiling the Maven Shade Plugin: A Comprehensive Guide

In today’s fast-paced world of software development, dependency management and build automation are essential for ensuring a seamless and…

By Lavneesh

2 min read

In today's fast-paced world of software development, dependency management and build automation are essential for ensuring a seamless and efficient development process. One such tool that has gained immense popularity in the Java community is Apache Maven. Maven not only manages dependencies but also simplifies the build process for Java applications.

In this blog post, we will delve into the Maven Shade Plugin, a powerful tool within the Maven ecosystem, and explore its utility in creating uber JARs or fat JARs — executable JAR files containing all the project dependencies. We will also walk through a step-by-step guide on how to use the Maven Shade Plugin and discuss some common use cases.

What is the Maven Shade Plugin?

The Maven Shade Plugin is a versatile tool that allows you to package your Java application along with its dependencies into a single, executable JAR file. This is particularly useful when deploying or distributing your application, as it ensures that all required libraries are bundled together, reducing the risk of dependency conflicts or missing components.

How to Use the Maven Shade Plugin

Add the plugin to your pom.xml file

First, you need to include the Maven Shade Plugin in your project's pom.xml file. Add the following snippet inside the <plugins> section of the <build> element:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                        <mainClass>com.example.Main</mainClass>
                    </transformer>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

Replace com.example.Main with the fully-qualified name of your application's main class.

Configure the plugin

In the <configuration> section of the plugin, you can customize various aspects of the shading process. Some common configurations include:

  • <minimizeJar>: Set this to true to minimize the resulting JAR size by removing unnecessary classes from the dependencies.
  • <filters>: Define inclusion and exclusion rules for the dependencies.
  • <relocations>: Relocate classes within the final JAR to avoid potential conflicts with other dependencies.

Build your project

Run the following command to build your project and create the shaded JAR:

mvn clean package

This command will generate the shaded JAR in the target directory of your project.

Configuration options

The Maven Shade Plugin offers a wide range of configuration options that allow you to customize the shading process and the generated JAR file. Here's an overview of some more configuration options:

<artifactSet>: Define a set of artifacts to include or exclude from the shaded JAR. Use the <includes> and <excludes> elements to define the patterns for inclusion and exclusion. For example:

<artifactSet>
    <includes>
        <include>com.example:*</include>
    </includes>
    <excludes>
        <exclude>org.apache.commons:*</exclude>
    </excludes>
</artifactSet>

<createDependencyReducedPom>: When set to true, this option generates a new POM file in the target directory, with the shaded dependencies removed. This can be useful when deploying the shaded artifact to a repository, as it prevents redundant dependencies from being included.

<createDependencyReducedPom>true</createDependencyReducedPom>

<shadedArtifactAttached>: By default, the shaded JAR file replaces the original JAR. If you set this option to true, the shaded JAR will be created alongside the original JAR, with a classifier specified by the <shadedClassifierName>.

<shadedArtifactAttached>true</shadedArtifactAttached>
<shadedClassifierName>shaded</shadedClassifierName>

<shadeSourcesContent>: When set to true, the plugin will also shade the sources of the project's dependencies. This can be useful for debugging purposes.

<shadeSourcesContent>true</shadeSourcesContent>

<transformers>: Customize the way resources are processed during the shading process by adding specific transformers. Some common transformers include:

  • org.apache.maven.plugins.shade.resource.ServicesResourceTransformer: Aggregates the content of META-INF/services files from multiple JARs to avoid conflicts when loading service providers.
  • org.apache.maven.plugins.shade.resource.AppendingTransformer: Merges files from different JARs by appending their content, which is useful for specific configuration files that need to be combined.
<transformers>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer" />
    <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
        <resource>META-INF/somefile.txt</resource>
    </transformer>
</transformers>

These are just a few of the many configuration options provided by the Maven Shade Plugin. By tailoring these options to your project's requirements, you can create a customized and optimized shaded JAR that meets your specific needs. Refer to the official Maven Shade Plugin documentation for a comprehensive list of configuration options and their descriptions.

Use Cases

The Maven Shade Plugin is beneficial in various scenarios, such as:

  1. Deploying microservices: Packaging your microservice and its dependencies into a single JAR makes deployment and scaling more straightforward.
  2. Creating self-contained command-line tools: Bundling everything into a single executable JAR simplifies distribution and usage.
  3. Resolving dependency conflicts: By relocating classes within the JAR, the Shade Plugin helps avoid potential classpath conflicts.