Build system


Detailed insight in the standard XP build system

We recommend using Enonic CLI to control your builds by default.


By default, XP projects use Gradle as the main build tool. This is a highly flexible Java-based utility that builds on the popular Maven project tools and code repository structures. Enonic provides a Gradle plugin that greatly simplifies the build process. If you used the starter-vanilla project to initialize your project, you will have all the basic tools you need to get going.


The build.gradle file located at your project root defines all the dependencies to other libraries.

There are three standard scopes (keywords) used in the dependency list

  • Compile (default gradle scope, compiles library and adds it to class path - standard for pure Java libraries)

  • Include (XP custom scope that merges the content of the library and its dependencies with your project - any code in your project overwrites the library files)

  • Webjar (Extracts the content of the specified Webjar - - placing it into the assets folder, using the version number as root folder)

Environment variables

The XP Home folder contains directories specific to a single XP instance. The home folder can be copied to multiple locations for developers working on multiple isolated projects. Enonic XP uses, by default, the home folder within your distribution as XP Home.

Enonic XP uses, by default, the JDK/JRE within your distribution or the location of your Java installation is used as Java Home. Gradel uses, by default, the location of your Java installation is used as Java Home

If you wish to change this behaviour, the following environment variables can be defined:


Defines the location of the home folder


Defines the location of Java

To set these variables use one of the following approaches:

export XP_HOME=/path/to/home
export JAVA_HOME=/path/to/xp-distro/jdk
set XP_HOME=c:\path\to\home
set JAVA_HOME=c:\path\to\xp-distro\jdk

Gradle Wrapper

The Gradle Wrapper is a file located in your projects root: gradlew for Linux/MacOS and gradle.bat for Windows.

The wrapper will download all necessary files to run Gradle and execute project specific build commands.


Enonic CLI’s enonic project build command automatically wraps and invokes the Gradle Wrapper.

With environment variables set, you may use Gradle directly to get the job done:

From your project folder root execute the following command:

Enonic CLI

enonic project build


./gradlew build


gradlew.bat build

The build will place any output artifacts in the project’s build/libs/ folder.


To builds and deploy an app to your XP Home, make sure XP_HOME is defined and execute the following command

Enonic CLI

enonic project deploy


./gradlew deploy


gradlew.bat deploy

The artifact is copied into the following location: $XP_HOME/deploy, where XP will automatically pick it up.

XP apps deployed via file (locally) are presented with a small blue icon in the Applications tool in XP Admin.

Development Mode

Enonic XP supports a so-called Development mode. When running in this mode, XP will automatically source JavaScript controllers directly from your project folder.

This may be convenient if you are developing with pure JavaScript and do not depend on build steps in your project.

You may activate dev mode when starting XP as follows:

Enonic CLI

enonic sandbox start --dev


$XP_INSTALL/bin/ dev


$XP_INSTALL/bin/ dev

Continuous building

Gradle also supports a continuous build mode. This will monitor your project assets for changes and run the specified task when something changes.

To use this with the deploy task, simply run the following command:


./gradlew deploy --continuous


gradlew.bat deploy --continuous

This will deploy and reload the application on the server when something changes in your project. The continuous deployment mode is most useful when coding Java, or other changes that require a full compile and re-deploy.