Showcase Application Development

This document explains the development workflow for the PatternFly Java Showcase application, which demonstrates all components, layouts, and charts in the library. It covers the dual-build system architecture (J2CL + Parcel), the Express development server, hot reload behavior, and debugging strategies.

For information about the showcase's deployment and publishing process, see Release Process. For general repository setup instructions, see Local Development Setup.

Architecture Overview

The showcase uses a hybrid development architecture that separates Java compilation from frontend asset bundling, then unifies them through an Express proxy server.

Development Mode Architecture

Sources: showcase/README.md5-31 showcase/package.json11-16 showcase/server.js1-64

Starting the Development Server

The development mode requires two terminal sessions running simultaneously.

Terminal 1: J2CL Compilation

Start the J2CL watch process from the repository root:

This command activates the showcase Maven profile and runs J2CL's incremental compilation mode. Wait for the message:

[INFO] -----  Build Complete: ready for browser refresh  -----

The J2CL plugin monitors Java source files under showcase/src/main/java and transpiles them to JavaScript in target/showcase/showcase.js Each compilation produces multiple bundle files (e.g., bundle_0.js, bundle_1.js) containing the transpiled Java code and dependencies.

Terminal 2: Parcel and Express Server

From the showcase directory, start the frontend build system:

This executes three concurrent processes defined in showcase/package.json15:

1. Parcel Watch (start:parcel): Monitors showcase/src/web/dev.html and bundles frontend assets on port 1235
2. Express Server (start:server): Runs showcase/server.js on port 1234 to unify J2CL and Parcel outputs
3. Browser Launch (open:browser): Opens http://localhost:1234 when the server is ready

Sources: showcase/README.md11-30 showcase/package.json11-15 showcase/pom.xml

File Watching and Hot Reload Behavior

The showcase exhibits different reload behaviors depending on which files are modified:

Why Manual Refresh for Java?

J2CL's watch mode detects changes and recompiles incrementally, but it has no mechanism to notify the browser of completed builds. The Express server serves static J2CL output files, so the browser must be manually refreshed to load the updated JavaScript.

Parcel, by contrast, uses WebSocket connections for hot module replacement (HMR), enabling automatic browser updates when frontend assets change.

Sources: showcase/README.md8-9 showcase/server.js38-53

Express Server Routing

The Express server in showcase/server.js acts as a reverse proxy and static file server, unifying J2CL's compiled JavaScript with Parcel's bundled assets.

Request Routing Diagram

Route Handlers

The server implements five routing strategies as defined in showcase/server.js24-58:

1. Parcel Asset Proxy (/parcel-assets/*): Proxies requests to Parcel's dev server on port 1235, enabling HMR WebSocket connections
2. J2CL Showcase Script (/showcase.js): Serves the main transpiled entry point from target/showcase/showcase.js
3. J2CL Bundles (/bundle*.js): Serves code-split bundles generated by J2CL
4. J2CL Source Maps (/sources/*): Serves Java source files for debugging (source map support)
5. Static Files: Serves all other files from target/showcase/
6. SPA Fallback (/*): Returns dev.html for client-side routing via PlaceManager

Sources: showcase/server.js16-63

Application Entry Points

Java Entry Point: Showcase.java

The Java application initializes in showcase/src/main/java/org/patternfly/showcase/Showcase.java:

Key initialization steps in Showcase.java77-142:

• Logger Configuration (Showcase.java78): Initializes Elemento's logger from URL parameters
• Navigation Component (Showcase.java80): Creates expandable vertical navigation with component/chart/layout groups
• PlaceManager Setup (Showcase.java81-87): Configures client-side routing with #/id(MAIN_ID) as the content container, sets page title pattern, and registers annotated places
• Page Structure (Showcase.java116-140): Builds the PatternFly Page component with masthead, sidebar, and main content area
• Navigation Binding (Showcase.java87): Links PlaceManager route changes to navigation item selection

Sources: showcase/src/main/java/org/patternfly/showcase/Showcase.java66-156

Frontend Entry Point: main.js

The frontend entry point showcase/src/web/main.js1-28 imports PatternFly CSS and chart web components:

The hljs object is exported to the global window scope (main.js27) so J2CL-compiled code can access it for code snippet highlighting.

Sources: showcase/src/web/main.js1-28

Chart Integration in Development

Charts in the showcase use web components that wrap React chart libraries. This integration requires coordination between J2CL, NPM packages, and Parcel bundling.

Chart Web Component Loading

Externs File for Type Safety

The externs file charts/src/main/resources/META-INF/externs/charts.externs.js prevents J2CL's compiler from mangling chart property names. It declares types for:

• Element Types: DonutElement, BulletElement, ChartElement (charts.externs.js29-130)
• Data Classes: Data, BulletData, LegendData, Threshold (charts.externs.js133-198)
• Callbacks: LabelsFn for custom label formatting (charts.externs.js203-204)

These declarations ensure that when Java code sets properties like element.data = ..., the JavaScript output preserves the exact property name data instead of renaming it to something like a during optimization.

Sources: charts/src/main/resources/META-INF/externs/charts.externs.js1-205 charts/npm/src/react-wrapper.js71-393

Component Development Pattern

Showcase pages for components follow a consistent structure:

Example Page Structure

Component pages implement the Place interface and use the @Place annotation for routing. The showcase/code.java JBang script extracts code snippets from special comment markers:

The script generates showcase/src/main/java/org/patternfly/showcase/Code.java with a snippets map, allowing pages to display source code alongside live examples.

Sources: showcase/code.java1-191

Production Build

The production build process differs significantly from development mode:

Production Build Flow

Key differences from development mode:

Sources: showcase/README.md32-42 showcase/package.json16-17 showcase/pom.xml

Common Development Tasks

Adding a New Component Example

1. Create a Java class in showcase/src/main/java/org/patternfly/showcase/component/ implementing Place
2. Annotate with @Place(route = "/components/my-component", title = "My Component")
3. Wrap code examples with // @code-start:snippet-id and // @code-end:snippet-id comments
4. Add the component to showcase/src/main/java/org/patternfly/showcase/Data.java for navigation
5. Restart J2CL watch (mvn j2cl:watch -P showcase)
6. Refresh browser to see the new page

Debugging Java Code

J2CL generates source maps that map JavaScript back to Java. To debug:

1. Open browser DevTools → Sources tab
2. Look for the sources folder containing Java files
3. Set breakpoints in Java code
4. Refresh the page to hit breakpoints

Source map files are served by the Express server's route handler at showcase/server.js50-53

Debugging Chart Web Components

Charts are React components wrapped in Lit web components. To debug:

1. Open browser DevTools → Elements tab
2. Inspect the <pfj-chart-*> element
3. Check the element's properties: element.data, element.width, etc.
4. Examine the shadow DOM for the rendered React component
5. Use React DevTools extension to inspect React component state

The React wrapper's lifecycle is managed by ReactWrapperElement in charts/npm/src/react-wrapper.js71-393

Updating PatternFly CSS Version

To update the PatternFly CSS dependency:

1. Edit showcase/package.json23 to change @patternfly/patternfly version
2. Run npm install in the showcase directory
3. Restart npm run watch
4. Verify styling changes in the browser

Testing Production Build Locally

To test the production build before deployment:

1. Run the production build: mvn clean package -P showcase,prod
2. Start the http-server: cd showcase && mvn com.github.eirslett:frontend-maven-plugin:npm@http-server
3. Open https://localhost:8080 (note HTTPS due to --ssl flag)
4. Accept the self-signed certificate warning

The production build uses showcase/cert.pem for local HTTPS testing.

Sources: showcase/README.md1-43 showcase/package.json1-42 showcase/server.js1-64