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:
# 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.
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 standard Enonic libraries or 3rd party 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 dependencies. Does not automatically include transitive dependencies, meaning you must explicitly declare transitive dependencies.
- Webjar
-
Custom Enonic 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 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 JDK.
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. |
