Extending the build system

📘

This is an article for advanced users of Frontastic.

In this article, we'll go through how to add custom tasks to the build system, so the Continuous Integration (CI) and Continuous Deployment (CD) pipeline. For example, it could be customer test runners or additional static code analyzers.

Overview

Frontastic uses Apache Ant-based build files to dispatch to all other build tools. The basic pipeline is already using extensions for common build steps and you can also add these extensions. The build process consists of the following steps, and they're usually run in the given order:

• clean: clean up old build artifacts
• initialize: set up fixture dependencies (databases)
• prepare: set up all directories, required for the build process
• test:
  • test-unit: run unit tests
  • test-spec: run specification tests
  • test-feature: run end to end tests
  • test-static: run static code analysis
• package: package build assets

You can hook into any of these steps with the build extensions.

The extension

While you can theoretically put a build extension directly into build.xml, we suggest extracting it into a dedicated code file and place it into src/ant in your project folder. This ensures your build.xml stays slim and upgradeable. You need to add it to the build.xml in your project directory, like:

<import file="${basedir}/src/ant/prettier.xml" />

The extension file itself (in this case prettier.xml) then looks like:

<?xml version="1.0" encoding="UTF-8"?>
<project>
    <target name="prettier" extensionOf="-test-static:main~hook">               
        <exec executable="../node_modules/prettier/bin-prettier.js" failonerror="true" dir="${basedir}">
            <arg value="--check" />                                             
            <arg value="src/js/**/*.{js,ts,jsx,tsx,json}" />                    
        </exec>                                                                 
    </target>
</project>

The name of the target enables you to run the task without running all the other tasks. The extensionOf attribute of the target specifies in which step of the overall build the task should be executed. More parameters of tasks (like depends) can be found in the Apache Ant documentation.

The <exec .../> task is probably the most commonly used Ant task here, it can be used to execute arbitrary commands, like prettier check … in this case.

You can also use all the other Ant tasks beyond exec in your build files. For more complex build extension examples you can look into paas/integration/build-commons/modules.

Extension points

Below is a list of all the extension points you can hook into:

• -clean:before~hook
• -clean:after~hook
• -initialize:before~hook
• -initialize:main~hook
• -initialize:after~hook
• -prepare:before~hook
• -prepare:after~hook
• -test-unit:before~hook
• -test-unit:main~hook
• -test-unit:after~hook
• -test-spec:before~hook
• -test-spec:main~hook
• -test-spec:after~hook
• -test-feature:before~hook
• -test-feature:main~hook
• -test-feature:after~hook
• -test-static:before~hook
• -test-static:main~hook
• -test-static:after~hook
• -package:before~hook
• -package:main~hook
• -package:after~hook