J2CL Integration

Relevant source files

This page documents the patternfly-java-j2cl module and its integration with the J2CL (Java-to-Closure-Compiler) toolchain. It covers module structure, Maven plugin configuration, compilation modes, and usage patterns for J2CL-based applications.

For GWT integration details, see GWT Integration. For JavaScript interop and externs configuration, see JavaScript Interop and Externs.

Purpose and Scope

The patternfly-java-j2cl module provides a dependency aggregation point for J2CL applications using PatternFly Java. Unlike GWT, J2CL does not require module descriptors (.gwt.xml files) and uses a different compilation approach based on the Closure Compiler. This module packages all necessary dependencies and resources for J2CL-based compilation.

Module Structure

The patternfly-java-j2cl module serves as an integration layer between PatternFly Java components and the J2CL toolchain.

Module packaging and dependencies

Sources: j2cl/pom.xml1-62

The module uses standard JAR packaging and aggregates the core PatternFly Java dependencies:

Dependency	Purpose
`patternfly-java-components`	UI component library
`patternfly-java-layouts`	Layout components

The module transitively includes patternfly-java-core, patternfly-java-icons, and patternfly-java-tokens through the components dependency.

Resource inclusion

The module packages JavaScript files from both source and resource directories:

This configuration ensures that JavaScript interop files and externs are included in the JAR artifact. The externs files define type information for external JavaScript libraries, enabling type-safe integration with web components (particularly for charts).

Sources: j2cl/pom.xml46-60

Maven Plugin Configuration

J2CL compilation is managed by the j2cl-maven-plugin from the KIE J2CL tools project. The plugin transpiles Java code to JavaScript using the Closure Compiler toolchain.

Plugin version management

Sources: pom.xml96 showcase/pom.xml36

The root POM defines the plugin version:

The plugin is configured in the parent POM's plugin management section with default settings applicable to all modules:

Sources: pom.xml179-186

Showcase configuration example

The showcase module demonstrates a complete J2CL configuration with development and production modes:

Property	Development Value	Production Value	Description
`j2cl.compilationLevel`	`BUNDLE_JAR`	`ADVANCED_OPTIMIZATIONS`	Closure Compiler optimization level
`j2cl.incremental`	`true`	`false`	Enable incremental compilation
`j2cl.sourcemaps`	`true`	`true`	Generate source maps for debugging

Sources: showcase/pom.xml202-218

KIE J2CL Tools BOM

The showcase imports the KIE J2CL tools BOM to manage processor dependencies:

This BOM provides version management for annotation processors used by J2CL:

org.kie.j2cl.tools.processors:annotations - Annotation definitions
org.kie.j2cl.tools.processors:common - Common processor utilities
org.kie.j2cl.tools.processors:processors - Annotation processors (provided scope)

Sources: showcase/pom.xml46-54 showcase/pom.xml92-103

Compilation Modes

J2CL supports multiple compilation levels through the Closure Compiler. PatternFly Java applications typically use two modes: BUNDLE_JAR for development and ADVANCED_OPTIMIZATIONS for production.

BUNDLE_JAR mode (development)

Sources: showcase/pom.xml40

The BUNDLE_JAR compilation level produces JavaScript bundles with minimal optimization:

Fast compilation: Suitable for rapid development cycles
Readable output: Generated JavaScript is relatively human-readable
No dead code elimination: All code is included
Large bundle size: Not suitable for production deployment

This mode is the default for the showcase development workflow:

ADVANCED_OPTIMIZATIONS mode (production)

The ADVANCED_OPTIMIZATIONS level applies aggressive optimizations through the Closure Compiler:

Dead code elimination: Unused code is removed
Minification: Code is compressed
Name mangling: Identifiers are shortened
Property renaming: Property names are optimized
Type-based optimizations: Uses type information for better optimization

The showcase production profile enables this mode:

Sources: showcase/pom.xml223-229

Compilation level comparison

Feature	BUNDLE_JAR	ADVANCED_OPTIMIZATIONS
Build speed	Fast (seconds)	Slow (minutes)
Bundle size	Large (~MB)	Small (~KB)
Debugging	Easy	Requires source maps
Production-ready	No	Yes
Incremental compilation	Supported	Not typically used

Sources: showcase/pom.xml40-42 showcase/pom.xml223-229

Incremental Compilation

Incremental compilation significantly reduces build times during development by only recompiling changed files and their dependents.

Enabling incremental compilation

Sources: showcase/pom.xml41

The j2cl-maven-plugin uses this property to configure incremental behavior:

Development workflow with watch mode

The showcase supports a watch mode for continuous incremental compilation. From the project root:

This command:

Compiles Java sources to JavaScript incrementally
Monitors source files for changes
Recompiles only changed files and their dependents
Outputs a message when build is complete: Build Complete: ready for browser refresh

The showcase README documents this workflow:

Changes to the Java code will be detected by the J2CL Maven plugin, but you need to reload the browser manually.

Sources: showcase/README.md6-15 showcase/pom.xml203-210

Production builds disable incremental compilation

For production builds, incremental compilation is disabled to ensure a complete, optimized build:

This ensures that all optimizations are applied consistently across the entire codebase without relying on cached intermediate results.

Sources: showcase/pom.xml227

Source Map Generation

Source maps enable debugging of transpiled JavaScript code by mapping it back to the original Java source files. PatternFly Java enables source maps in both development and production modes.

Configuration

Sources: showcase/pom.xml42 showcase/pom.xml206

The plugin configuration uses this property:

Generated artifacts

When source maps are enabled, the plugin generates:

showcase.js - The transpiled JavaScript bundle
showcase.js.map - The source map file
sources/ - Directory containing original Java source files

The source map file contains JSON data mapping JavaScript positions to Java source positions, enabling browser developer tools to display Java source code during debugging.

Debugging workflow

Build with source maps enabled
Open browser developer tools
Navigate to the Sources tab
The debugger displays original Java files instead of transpiled JavaScript
Set breakpoints in Java code
Inspect variables using Java names (not mangled JavaScript names)

This capability is particularly valuable when using ADVANCED_OPTIMIZATIONS, where the generated JavaScript is heavily obfuscated.

Sources: showcase/pom.xml203-210

Application Integration

This section describes how to integrate PatternFly Java with J2CL in an application project.

Dependency configuration

Sources: README.md43-73

Import the BOM in your project's pom.xml:

Add the J2CL integration dependency:

Key differences from GWT

Aspect	GWT	J2CL
Module descriptor	Required (`.gwt.xml`)	Not required
Packaging	`gwt-lib`	`jar`
Plugin	`gwt-maven-plugin`	`j2cl-maven-plugin`
Compiler	GWT Compiler	Closure Compiler
Optimization	Multiple levels	Closure levels

No module inheritance needed

Unlike GWT applications that must inherit from org.patternfly.PatternFly, J2CL applications do not require any module descriptor files. The J2CL toolchain automatically discovers and processes all Java sources and their dependencies.

Sources: README.md75-81 j2cl/pom.xml30-31

Plugin configuration example

Configure the j2cl-maven-plugin in your application's pom.xml:

Sources: pom.xml179-186 showcase/pom.xml202-218

Build commands

Development build with incremental compilation:

Production build with optimizations:

The production profile should configure:

compilationLevel: ADVANCED_OPTIMIZATIONS
incrementalEnabled: false
sourcemaps: true (optional, for debugging)

Sources: showcase/README.md11-42

External Dependencies

J2CL applications using PatternFly Java must provide certain external resources that are not bundled with the Java library.

PatternFly CSS stylesheets

PatternFly Java does not bundle CSS stylesheets. Applications must include PatternFly CSS separately. The README emphasizes this:

PatternFly Java does not come with stylesheets. You are expected to include or bundle the necessary stylesheets yourself.

See the PatternFly getting started guide for stylesheet integration instructions.

Chart web components

To use chart components, applications must install the @patternfly-java/charts NPM package:

Import in your JavaScript:

This package provides web component wrappers for PatternFly React charts, enabling use from Java code through the J2CL externs system.

Sources: README.md84-103

HTML template requirements

The application HTML must load the generated JavaScript bundle:

The showcase demonstrates this pattern in its development and production HTML templates.

Sources: README.md84-87 showcase/pom.xml1-252