JS Transpiler Gradle Plugin

The JS Transpiler Gradle plugin lets you run metal-cli to build Metal.js code, compile Soy files, and transpile ES6 to ES5.

The plugin has been successfully tested with Gradle 4.10.2.

Usage

To use the plugin, include it in your build script:

buildscript {
    dependencies {
        classpath group: "com.liferay", name: "com.liferay.gradle.plugins.js.transpiler", version: "2.4.36"
    }

    repositories {
        maven {
            url "https://repository-cdn.liferay.com/nexus/content/groups/public"
        }
    }
}

apply plugin: "com.liferay.js.transpiler"

There are two JS Transpiler Gradle plugins you can apply to your project:

JS Transpiler Plugin

The JS Transpiler plugin automatically applies the JS Transpiler Base Plugin.

The plugin adds two tasks to your project:

NameDepends OnTypeDescription
downloadMetalClidownloadNodeDownloadNodeModuleTaskDownloads metal-cli in the project’s node_modules directory.
transpileJSdownloadMetalCli, expandJSCompileDependencies, npmInstall, processResourcesTranspileJSTaskBuilds Metal.js code.

By default, the downloadMetalCli task downloads the version 1.3.1 of metal-cli. If the project’s package.json file, however, already lists the metal-cli package in its dependencies or devDependencies, the downloadMetalCli task is disabled.

The transpileJS task is automatically configured with sensible defaults, depending on whether the java plugin is applied:

Property NameDefault Value
sourceDirThe directory META-INF/resources in the first resources directory of the main source set (by default, src/main/resources/META-INF/resources).
workingDir"${sourceSets.main.output.resourcesDir}/META-INF/resources"

The plugin also adds the following dependencies to tasks defined by the java plugin:

NameDepends On
classestranspileJS

The plugin adds a new configuration to the project called soyCompile. If one or more dependencies are added to this configuration, they will be expanded into temporary directories and passed to the transpileJS task as additional soyDependencies values.

JS Transpiler Base Plugin

The JS Transpiler Base plugin automatically applies the com.liferay.node plugin.

The plugin adds a new configuration to the project called jsCompile. If one or more dependencies are added to this configuration, they will be expanded into sub-directories of the node_modules directory, with names equal to the names of the dependencies.

The plugin also adds one task to your project:

NameDepends OnTypeDescription
expandJSCompileDependencies-DefaultTaskExpands the additional configured JavaScript dependencies. The task itself does not do any work, but depends on a series of Copy tasks called expandJSCompileDependency${file}, which expand each dependency declared in the jsCompile configuration into the node_modules directory.

All the tasks of type ExecuteNpmTask whose name starts with "npmRun" are configured to depend on expandJSCompileDependencies. This means that, before running any script declared in the package.json file of the project, all the jsCompile dependencies will be expanded into the node_modules directory.

Tasks

TranspileJSTask

Tasks of type TranspileJSTask extend ExecuteNodeScriptTask, so all its properties and methods, such as args, inheritProxy, and workingDir, are available. They also have the following properties set by default:

Property NameDefault Value
scriptFile"${downloadMetalCli.moduleDir}/index.js"
soySrcIncludes["**/*.soy"]
srcIncludes["**/*.es.js*", "**/*.soy.js*"]

The purpose of this task is to run the build command of metal-cli to build Metal.js code from sourceDir into the workingDir directory.

Task Properties

Property NameTypeDefault ValueDescription
bundleFileNameStringnullThe name of the final bundle file for formats (e.g., globals) that create one. It sets the --bundleFileName argument.
globalNameStringnullThe name of the global variable that holds exported modules. It sets the --globalName argument. This is only used by the globals format build.
moduleNameStringnullThe name of the project that is being compiled. All built modules are stored in a folder with this name. It sets the --moduleName argument. This is only used by the amd format build.
modulesString"amd"The format(s) that the source files are built to. It sets the --format argument.
skipWhenEmptybooleantrueWhether to disable the task and remove its dependencies if the sourceFiles property does not return any file at the end of the project evaluation.
sourceDirFilenullThe directory that contains the files to build.
sourceFilesFileCollection[]The Soy and JS files to compile. (Read-only)
sourceMapsSourceMapsenabledWhether to generate source map files. Available values include disabled, enabled, and enabled_inline.
soyDependenciesSet<String>["${npmInstall.workingDir}/node_modules/clay*/src/**/*.soy", "${npmInstall.workingDir}/node_modules/metal*/src/**/*.soy"]The path GLOBs of Soy files that the main source files depend on, but that should not be compiled. It sets the --soyDeps argument.
soySkipMetalGenerationbooleanfalseWhether to just compile Soy files, without adding Metal.js generated code, like the component class. It sets the --soySkipMetalGeneration argument.
soySrcIncludesSet<String>[]The path GLOBs of the Soy files to compile. It sets the --soySrc argument.
srcIncludesSet<String>[]The path GLOBs of the JS files to compile. It sets the --src argument.

The properties of type File support any type that can be resolved by project.file. Moreover, it is possible to use Closures and Callables as values for the int and String properties to defer evaluation until task execution.

Task Methods

MethodDescription
TranspileJSTask soyDependency(Iterable<?> soyDependencies)Adds path GLOBs of Soy files that the main source files depend on, but that should not be compiled.
TranspileJSTask soyDependency(Object... soyDependencies)Adds path GLOBs of Soy files that the main source files depend on, but that should not be compiled.
TranspileJSTask soySrcInclude(Iterable<?> soySrcIncludes)Adds path GLOBs of Soy files to compile.
TranspileJSTask soySrcInclude(Object... soySrcIncludes)Adds path GLOBs of Soy files to compile.
TranspileJSTask srcInclude(Iterable<?> srcIncludes)Adds path GLOBs of JS files to compile.
TranspileJSTask srcInclude(Object... srcIncludes)Adds path GLOBs of JS files to compile.
Was this article helpful?
0 out of 0 found this helpful