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.
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.
Sources: pom.xml106-108 pom.xml87
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
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
Before starting development, perform a full build to ensure all dependencies are correctly installed and code generation completes:
This command:
Version.java, icon sets, and design tokens from frontend assetsSources: core/pom.xml82-100 tokens/pom.xml44-93 icons/pom.xml60-93 pom.xml293-454
| 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
PatternFly Java provides several Maven profiles to optimize the development workflow:
For rapid iteration during development, use the quickly property to skip time-consuming validation steps:
This profile disables:
checkstyle.skip=true)editorconfig.skip=true)enforcer.skip=true)impsort.skip=true)license.skip=true)maven.javadoc.skip=true)skipITs=true)skipTests=true)Warning: Always run a full build before committing changes to ensure code quality standards are met.
Sources: pom.xml464-481
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)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
PatternFly Java enforces code quality through automated checks during the build process. These checks run during the verify phase:
Sources: pom.xml342-414
| 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 |
Run quality checks without a full build:
Sources: pom.xml342-414
| 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/ |
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
After successfully building the project:
CONTRIBUTING.md in the repository rootSources: pom.xml1-599 showcase/pom.xml1-252 showcase/README.md1-43
Refresh this wiki