Local Development Setup

Relevant source files

This page provides instructions for setting up a local development environment to contribute to PatternFly Java. It covers prerequisites, repository cloning, dependency installation, and basic build commands. For information about developing the showcase application specifically, see Showcase Application Development. For understanding the differences between GWT and J2CL compilation targets, see GWT vs J2CL.

Prerequisites

PatternFly Java requires the following tools to be installed on your development machine:

Tool	Minimum Version	Required For	Configuration Source
Java Development Kit (JDK)	21	Compilation and runtime	pom.xml106
Apache Maven	3.9.9	Build system	pom.xml108
Git	Any recent version	Source control	-
Node.js	v24.10.0	Frontend tooling (optional)	pom.xml87

Note: Node.js is automatically installed by the Frontend Maven Plugin during builds that require it. Manual installation is only necessary if you want to run frontend commands directly.

Prerequisites Diagram

Sources: pom.xml106-108 pom.xml87

Cloning the Repository

Clone the PatternFly Java repository from GitHub:

The repository structure follows a multi-module Maven layout with the following top-level directories:

Sources: pom.xml113-126

Project Structure Overview

The repository consists of the following module types:

Module Type	Modules	Purpose
Foundation	`core`, `tokens`, `icons`	Base classes, design tokens, icon system
UI Libraries	`components`, `layouts`, `charts`	PatternFly components and layouts
Platform Targets	`gwt`, `j2cl`	Packaging for GWT and J2CL applications
Extensions	`codeeditor`, `finder`	Optional component extensions
Build Support	`build-config`, `code-parent`, `bom`	Build configuration and dependency management
Documentation	`showcase`	Live demonstration application

Sources: pom.xml113-126 README.md107-121

Initial Build

Before starting development, perform a full build to ensure all dependencies are correctly installed and code generation completes:

This command:

Downloads dependencies - Maven retrieves all declared dependencies from Maven Central and other configured repositories
Generates code - JBang scripts generate Version.java, icon sets, and design tokens from frontend assets
Compiles Java sources - All modules compile in dependency order
Runs quality checks - Executes checkstyle, license header validation, import sorting, and editorconfig verification
Packages artifacts - Creates JAR files for all modules

Build Process Diagram

Sources: core/pom.xml82-100 tokens/pom.xml44-93 icons/pom.xml60-93 pom.xml293-454

Expected Build Time

Build Type	Approximate Duration	Notes
Initial build (`mvn clean install`)	5-10 minutes	Includes dependency download, code generation, all quality checks
Incremental build (`mvn install`)	1-3 minutes	Skips code generation if sources unchanged
Quick build (`mvn install -Dquickly`)	30-60 seconds	Skips tests and quality checks (see below)

Sources: pom.xml464-481

Development Build Profiles

PatternFly Java provides several Maven profiles to optimize the development workflow:

Quick Build Profile

For rapid iteration during development, use the quickly property to skip time-consuming validation steps:

This profile disables:

Checkstyle validation (checkstyle.skip=true)
Editorconfig verification (editorconfig.skip=true)
Maven enforcer rules (enforcer.skip=true)
Import sort checking (impsort.skip=true)
License header validation (license.skip=true)
Javadoc generation (maven.javadoc.skip=true)
Integration tests (skipITs=true)
Unit tests (skipTests=true)

Warning: Always run a full build before committing changes to ensure code quality standards are met.

Sources: pom.xml464-481

Building Specific Modules

To build a single module and its dependencies:

Maven Reactor Options:

-pl <module> - Build only the specified module(s)
-am - Also build dependencies (--also-make)
-amd - Also build dependents (--also-make-dependents)

Building the Showcase

The showcase application is excluded from the default build. To include it:

For production-optimized showcase build:

Sources: pom.xml557-562 showcase/pom.xml222-250

Code Quality Enforcement

PatternFly Java enforces code quality through automated checks during the build process. These checks run during the verify phase:

Sources: pom.xml342-414

Code Quality Tools

Tool	Purpose	Configuration
Checkstyle	Java code style validation	pom.xml237-253 - Uses `wildfly-checkstyle/checkstyle.xml`
License Maven Plugin	Apache 2.0 header validation	pom.xml193-234 - Template at `build-config/src/main/resources/etc/license.txt`
Impsort Maven Plugin	Import statement ordering	pom.xml164-172 - Groups: `java.`, `javax.`, `jakarta.`, `org.`, `io.`, `com.`
Editorconfig Maven Plugin	Whitespace and line ending validation	pom.xml141-151 - Follows `.editorconfig` rules

Manual Code Quality Checks

Run quality checks without a full build:

Sources: pom.xml342-414

Common Build Issues and Solutions

Issue	Symptom	Solution
Missing generated files	Compilation errors in `Version.java`, `Token.java`, `IconSets.java`	Run `mvn clean generate-sources`
Maven version too old	Enforcer plugin failure	Upgrade to Maven 3.9.9+ (pom.xml256-276)
Java version mismatch	Compilation errors or enforcer failure	Install JDK 21+ (pom.xml256-276)
Checkstyle failures	Build fails in verify phase	Run `mvn checkstyle:check` for details; review WildFly checkstyle rules
License header missing	License plugin failure	Run `mvn license:format` to auto-add headers
Import order incorrect	Impsort plugin failure	Run `mvn impsort:sort` to auto-fix
Node installation fails	Frontend plugin errors	Check internet connectivity; Plugin downloads Node to `./node/`

Repository Configuration Files

Key configuration files in the repository root:

File	Purpose
`.editorconfig`	Code formatting rules for editors
`pom.xml`	Root Maven POM - module aggregation, plugin management
`code-parent/pom.xml`	Parent POM for code modules - dependency management
`bom/pom.xml`	Bill of Materials - version management for consumers
`build-config/`	Shared build resources (checkstyle suppressions, license template)
`degraph-style.json`	Dependency graph visualization styling

Sources: pom.xml1-599 code-parent/pom.xml1-105 bom/pom.xml1-256

Next Steps

After successfully building the project:

For showcase development: See Showcase Application Development for the dual-build system (J2CL watch + Parcel dev server)
For understanding compilation targets: See GWT vs J2CL for packaging differences
For exploring components: See Component Library for documentation on implemented components
For contributing: Review CONTRIBUTING.md in the repository root

Maven Command Reference

Sources: pom.xml1-599 showcase/pom.xml1-252 showcase/README.md1-43