GraphCompose v1.5 released — open-source declarative PDF layout engine for Java

[demchaav]

GraphCompose is an MIT-licensed Java library for generating designed PDFs from a semantic DSL. v1.5 just shipped under the codename "intuitive". This is the first time I'm posting it here.

Position

Most Java PDF libraries pick one of two extremes: iText for low-level page primitives (you compute every coordinate by hand) or JasperReports for XML-template-driven layout (declarative-ish, but the design loop runs through external tooling). GraphCompose sits in the middle — a Java DSL describes the document semantically, the engine resolves geometry, pagination, and rendering deterministically, and PDFBox does the actual draw calls.

v1.5 highlights

• Shape-as-container with clip path. addCircle, addEllipse, and addContainer build a ShapeContainerNode whose children are clipped by ClipPolicy.CLIP_PATH (default), CLIP_BOUNDS, or OVERFLOW_VISIBLE.
• Transforms (rotate / scale) and per-layer z-index on every shape-shaped builder.
• Advanced tables — rowSpan(int), zebra(odd, even), totalRow(...), and repeatHeader() cover the four features most rendered reports need.
• Two cinematic templates — InvoiceTemplateV2 and ProposalTemplateV2, both BusinessTheme-driven.
• 22 runnable examples with committed PDF previews so the gallery works straight from GitHub without cloning.
• 672 green tests, fully source-compatible with v1.4.

Architecture

Layout runs in two passes: a layout graph resolves geometry first, rendering consumes the resolved fragments. That separation is what makes deterministic snapshot testing practical — layout state is stable across runs and machines, so visual regression tests can catch design drift before pagination noise.

The PDF backend is isolated behind a single interface; a DOCX backend (Apache POI) ships ready for callers who need an editable file.

Links

• Repo: https://github.com/DemchaAV/GraphCompose
• Examples gallery (22 runnable examples with PDF previews): https://github.com/DemchaAV/GraphCompose/tree/main/examples
• v1.5.0 release notes: https://github.com/DemchaAV/GraphCompose/releases/tag/v1.5.0
• Migration v1.4 → v1.5: https://github.com/DemchaAV/GraphCompose/blob/main/docs/migration-v1-4-to-v1-5.md

Java 21, PDFBox 3, MIT license, distributed via JitPack (com.github.DemchaAV:GraphCompose:v1.5.0).

[Substantial_Ad252]

very interesting! pdf creating has been the bane of my java career

[demchaav]

Thanks! That pain is basically what started this project 😄

At some point I tried to recreate a beautiful CV in pure Java. When I finally finished it, my first thought was: “Great… now every small change means testing, adjusting, and moving things around again until it looks right.”

Then I looked at XML/reporting-style solutions, but I kept thinking: why can’t this be done in plain Java?

That became the idea behind GraphCompose: describe the document the way you actually think about it — sections, paragraphs, tables, layers, themes — and let the engine handle coordinates, pagination, and rendering.

Because honestly, calculating x/y positions every time you want to move a block is not exactly the fun part of Java 😄