PDFx: a backwards-compatible PDF extension for bundling many documents into one file

The problem PDFx solves: many documents, one attachment

Merging PDFs is easy. Merging them without losing the seams is not. A conventional merge produces a flat page sequence, so the reader can no longer tell where one document ended and the next began, and extracting a single document afterwards means guessing page ranges. PDFx attacks that by keeping the documents as documents. The README states that the files produced are fully valid PDFs and that opening them anywhere shows every page in sequence, while opening them in PDFx splits the file back into the original documents. The format is described as an open, backwards compatible extension of PDF, and plain single PDFs work as they are.

The audience is narrow but real: people who assemble packets. Contracts plus exhibits, a report plus its appendices, a set of scans that belong together but originate separately. The repository topics list pdf-generator, pdf-parser and pdf-viewer, which matches that framing: this is a tool for building and reading collections, not for editing page content.

One embedded JSON manifest does the whole job

The README is unusually direct about the mechanism: the entire trick is one embedded JSON manifest, and SPEC.md is described as short. That is the design decision worth understanding. PDFx does not invent a new container, a sidecar file or a zip with a .pdf extension. It writes a normal PDF and attaches a manifest that records which pages belong to which source document. A reader that ignores the manifest sees a linear PDF, which is why the backwards compatibility claim holds. A reader that understands the manifest can regroup the pages.

The consequence cuts both ways. Because the structure lives in metadata rather than in the page stream, the file stays portable and previews correctly in browsers and email clients. But the manifest is also the only place the document boundaries exist. Anything that rewrites the PDF and drops unknown embedded data will silently flatten a bundle into an ordinary merged PDF. The README does not document a recovery path for that case, and it does not document rollback either, so treat the manifest as the artifact to protect.

The application side is a free-floating 2D canvas. According to the README, each document renders as a horizontal strip of pages and documents stack vertically; you reorder or remove them and then export. Rendering is done with pdf.js and assembly with pdf-lib, both named in the README. The stack-and-strip layout is a deliberate choice over a single scrolling list: it keeps the boundary between documents visible while you arrange them.

Installing PDFx and exporting a first bundle

The README gives the development path through Yarn. Run the install first; note that the package.json postinstall hook runs electron-builder install-app-deps, a native build script and two asset-copying scripts, so the install is heavier than a pure JavaScript dependency tree.

yarn              # install
yarn dev          # run in development

yarn dev starts the Electron app through electron-vite in watch mode. There is also a browser path, which is useful if you want to check the canvas behaviour without the desktop shell:

yarn dev:web      # run on the web

For a distributable build, the README lists one script per platform. The package.json names build:mac, build:win and build:linux, plus a Flatpak variant on Linux.

yarn build:mac    # build:win for windows, build:linux for linux

The README also states that the AI assistant needs a provider API key, and that you copy .dev.vars.example to .dev.vars and set your key for Google, Anthropic or OpenAI. The repository root contains .dev.vars.example and dev-vars.ts, which matches that instruction. Without that file the rest of the application still runs; only the assistant is affected.

First real use, per the README: drag and drop .pdf files, images or folders anywhere in the window, arrange the strips, then press Export PDF to save the collection as one file. The README does not state a page or file count limit for a bundle.

Where PDFx is the wrong tool

The clearest limitation is the assumption of a cooperating reader. If your recipient will open the file in a viewer that is not PDFx, they get a merged PDF and nothing else. The document boundaries are still in the file, but they are invisible. For a one-way delivery to an unknown audience, a plain merge or a zip of separate files communicates the structure more honestly, because a zip cannot be mistaken for a single document.

There is no indication in the README or the repository layout that PDFx edits page content. It renders, arranges and assembles. If you need to annotate, redact, sign or reflow pages, this is not that application, and the README does not claim otherwise.

The AI assistant is the second boundary. It depends on an external provider key, which means the feature has a network dependency and a per-provider cost that the MIT licence on the code does not cover. The README names Google, Anthropic and OpenAI as options but does not describe what the assistant does to your documents, so anyone handling confidential files should treat that feature as out of scope until they have read the source.

Finally, the platform badges list macOS, Windows and Linux, but the download link in the README points at a single PDFx.zip with an Apple logo on the badge. The README does not document prebuilt installers for the other two platforms, so Windows and Linux users should expect to build from source.

How PDFx differs from a plain merge with qpdf or Ghostscript

The obvious alternative is a command-line merge, for example qpdf or Ghostscript, or the merge feature built into any desktop PDF suite. Those tools solve a different problem: they produce a page sequence and stop. There is no notion of a document inside the output, so the grouping you had before the merge is gone.

PDFx keeps the grouping and pays for it with a format extension. That is the real difference in approach, and it explains the project's shape. A merge tool is a filter that reads pages and writes pages. PDFx is a format definition plus a viewer, which is why the repository ships a SPEC.md and why the viewer is described as minimal. The viewer exists to make the manifest useful, not to compete on editing features.

If you are generating bundles programmatically, the comparison matters in the other direction: with qpdf you shell out and you are done, while with PDFx you either use the desktop app or implement the manifest yourself from SPEC.md. The README does not describe a CLI or a library API for writing bundles, so the second option is the one to plan for.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-16. Releases are sparse: v0.2.0 on 2026-08-10, and before it a v2026.6.1-beta.0 on 2026-07-02. The version in package.json is 0.2.0, which matches the release. Two releases in the visible history, one of them a beta, means you should read the release notes before upgrading rather than assuming a compatibility policy.

The upgrade cost is concentrated in two places. First, the format itself: SPEC.md defines the manifest, so a change there affects every file you have already produced, and the README does not document a migration or versioning scheme for old bundles. Second, the toolchain. The postinstall hook builds a native component and copies OCR and PDF assets, and the build scripts call electron-vite and electron-builder separately. A Node or Electron major upgrade is therefore a real maintenance event, not a version bump.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. MIT also means no warranty. Note that the AI providers named in the README are separate services with their own terms; the MIT grant covers the code in this repository, not the API calls it makes. This is a description of the licence text, not legal advice.

Editorial conclusion

Adopt PDFx if you need to hand one file to someone and still keep the original document boundaries intact, and if you accept that the receiving side needs PDFx to recover those boundaries. Do not adopt it as a general PDF editor, and do not expect the AI assistant to work without a provider key. Before committing, read SPEC.md and confirm the manifest layout is something your own pipeline can emit, then check whether the native build step in postinstall succeeds on your platform.

Frequently asked questions

Official sources

1. AlexandrosGounis/pdfx on GitHub
2. License: MIT
3. Project website
4. README
5. Releases