Docs Developer Site
DeveloperDocsXpStableDevelopmentBuild

Building apps

Contents

This section explains the details of the Enonic XP build system

Main builder

As explained in the code section, Enonic development projects use Gradle as the main build tool.

Gradle is built around the popular Maven ecosystem. Gradle is used because Enonic apps are packaged and deployed as .jar (Java) files in the end.

Enonic supports popular TypeScript/JavaScript tooling such as TSUP, NPM and webpack to run on top of Gradle. Try one or our Starters to see it in action.

The Gradle build files are described below

gradle.properties

This file specifies common properties for any Enonic project:

Sample gradle.properties file 
# Gradle Project settings
projectName = vanilla (1)
version = 1.0.0-SNAPSHOT (2)

# XP App values
appDisplayName = Vanilla Example (3)
appName = com.acme.example.vanilla (4)
vendorName = Acme Inc
vendorUrl = https://example.com
xpVersion = 7.13.3 (5)

# Settings for publishing to a Maven repo
group = com.acme.example (6)
1 Project name is used for the output file i.e. this will produce an app file called vanilla-<version>.jar
2 Version is important metadata, used to identify different releases of an app.
3 appDisplayName is used when listing the applications in UI
4 appName must be unique across all apps, this is also stored in CMS content is created, used as a namespace
5 Minimum version of XP required for the app. This property is typically also used to determine which xp core libraries to use by build.gradle

build.gradle

This is the main build file. It controls available build settings, dependencies and more.

Sample gradle.properties file 
plugins { (1)
    id 'com.enonic.xp.app' version '3.4.0'
}

app { (2)
    name = "${appName}"
    displayName = "${appDisplayName}"
    vendorName = "${vendorName}"
    vendorUrl = "${vendorUrl}"
    systemVersion = "${xpVersion}"
}

dependencies { (3)
    implementation "com.enonic.xp:core-api:${xpVersion}"
    implementation "com.enonic.xp:portal-api:${xpVersion}"
    include "com.enonic.xp:lib-content:${xpVersion}"
    include "com.enonic.xp:lib-portal:${xpVersion}"
}

tasks.register('dev', Exec) { (4)
    commandLine './gradlew', 'deploy', '-t'
}

repositories { (5)
    mavenLocal()
    mavenCentral()
    xp.enonicRepo()
}
1 Enonic provides a Gradle plugin to simplify the build setup.
2 Applies values from gradle.properties.
3 Define dependencies to libraries, notice the {xpVersion} which uses the value from gradle.properties.
4 Enables dev mode for the project
5 Defines Maven repos where Gradle will look for dependencies.

Dependencies

Easily include Enonic libraries or Java dependencies in your app via the dependencies section.

Each dependency must be prefixed with a scope for specific building instructions. The available scopes are:

Include

Standard scope when adding Enonic libraries to your project. Resource files in the library are merged into your app. Files in your app overwrites files with the same name in the library. Dependencies of the library are transitively included.

Implementation

Typically used for Java dependenceis. Does not automatically include transitive dependencies, meaning you must explicitly declare transitive dependencies.

Webjar

Custom Enonicwq scope that extracts the content of the specified Webjar - https://www.webjars.org/ - placing it into the assets folder, using the version number as root folder

Compiler

The Enonic XP SDK distros bundles the Java Development Kit (JDK), which includes the compiler needed to build Enonic apps.

When building applications without using Enonic CLI, you must tell Gradle which compiler (Enonic XP distro) to use. This is done by setting the JAVA_HOME environment variable.

JAVA_HOME

Defines the location of the Java compiler.

To set the environment variable, use one of the following approaches:

Linux/MacOS 
export JAVA_HOME=/path/to/xp-distro/jdk
Windows 
set JAVA_HOME=c:\path\to\xp-distro\jdk

Building

Builds are initialized via the Gradle Wrapper. This 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 execute your build.

Using Enonic CLI, simply run the following command from your project folder:

Enonic CLI

enonic project build

To manually trigger Gradle builds, make sure JAVA_HOME is defined, and run the following command:

OSX/Linux

./gradlew build

Windows

gradlew.bat build

The build will place any output artifacts (app or library files) into your project’s build/libs/ folder.

Deploying

To deploy an app to your sandbox:

Enonic CLI

enonic project deploy

To do this manually, make sure XP_HOME is defined and execute the following command

Linux/MacOS

./gradlew deploy

Windows

gradlew.bat deploy

This command copies the artifact (application file) into your sandbox' $XP_HOME/deploy folder. XP will then automatically install and start it.

XP apps deployed via file are presented with a small blue icon in the Applications admin tool.

Dev Mode

Using dev mode is generally recommended, as it saves time by providing real-time updates of your app

By running your sandbox in dev mode, it will automatically detect and load changes to your application source files, including JavaScript controllers and schemas. It does this by reading the files directly from the application project folder instead of using the compiled application file.

Enonic CLI

enonic sandbox start --dev

Linux/MacOS

$XP_INSTALL/bin/server.sh dev

Windows

$XP_INSTALL/bin/server.sh dev

Dev mode should never be used in production. Doing so may cause both security and performance issues.

In addition to running XP in dev mode, your application may contain files that require compilation (including transpilation). This means that must build the files for every change. For instance, if you use TypeScript, these files won’t be picked up by default.

Modern XP projects support this out of the box, simply replace the build and deploy command with this:

Enonic CLI

enonic project dev

Linux/MacOS

./gradlew dev

Windows

gradlew.bat dev

Development mode also disables some of XP’s caching mechanisms. To make the development workflow as smooth as possible, XP tries to invalidate caches for your static assets. This is to prevent you from getting stale resources so that what you see in the browser is always as up to date as possible.
XP 7.x defaults to the Nashorn JavaScript engine for executing JavaScript. For an overview over what JavaScript features Nashorn supports, see this feature table.

Contents

Contents