TPPDF: building PDFs on Apple platforms with a command API

A document described in commands

TPPDF is described as a simple-to-use PDF builder for iOS and macOS written in Swift, and the header line is blunter, a fast PDF builder for iOS and macOS using simple commands to create advanced documents. That word commands is the key to the design. Instead of laying out a page through a graphics context, you assemble a document from a vocabulary of content elements, each of which knows how to measure and draw itself, and the library handles the parts that are tedious by hand, the page breaks, the alignment, the table sizing, the running header and footer. It was created and maintained by Philip Niedertscheider and the contributors to the project, it ships under the MIT licence, it is available through Swift Package Manager, and the documentation lives at techprimate.github.io/TPPDF. For a platform where printing is a first class system capability, having a document layer that speaks in commands rather than in coordinates is a reasonable thing to want.

Three steps from an empty document to a file

The getting started section in the README is the whole tutorial, and it fits on a screen. First you create a document with a paper format:

let document = PDFDocument(format: .a4)

Then you add information to a container, in this case the centred content area:

document.add(.contentCenter, text: "Create PDF documents easily.")

And then you render the document and get a URL back:

let generator = PDFGenerator(document: document)
let url  = try generator.generateURL(filename: "Example.pdf")

The three calls map to the three stages of any document job, deciding the page geometry, placing content, and writing the file. The container argument is the notable part, since naming .contentCenter as the destination rather than passing coordinates is what lets the library handle alignment, and the generator is what applies pagination across the finished content. The README points to the Usage document for the rest, and it is there that the full vocabulary is laid out.

The feature list reads like a layout engine checklist

The feature list is long, and it is the best catalogue of what the library handles. There is a page header and footer, and both can contain images and horizontal line separators of their own. Layout includes dynamic content with page alignment, custom spacing, custom indentation, and a custom top offset, which the list notes is good for layered rendering. Tables are covered in depth, with cell alignment, custom table styling, cell merging, and automatic page breaking across pages, and there is a multi-column section layout. Text support includes attributed strings, hyperlinks in text, and an image caption. Images can be placed anywhere, given a custom size fit, and compressed. The document can carry PDF metadata, and there is native progress tracking using Foundation.Progress. One entry deserves singling out, because it is a design decision rather than a feature, the ability to generate PDF files directly to handle large PDF files, with a link to a discussion of lowering memory when generating large PDFs.

Running the sample project across the platform matrix

The repository ships a runnable project and the README explains how to run it. You clone the repository and install XcodeGen with brew bundle, you run make generate-example and then open Example/Example.xcodeproj, and you run the Example scheme on iOS 16 or later, macOS 12 or later, Mac Catalyst, tvOS 16 or later, visionOS 1 or later, or watchOS 9 or later. The platform list is not incidental, because the behaviour differs by target. iOS, macOS, Mac Catalyst, tvOS and visionOS display the generated PDFs, while watchOS reports generation success or errors without a PDF viewer, which is what you would expect from a platform that cannot show a document. The project is generated rather than committed, so you edit Example/Example.yml to change the project configuration and then regenerate it, and for command line builds there is make build-example-<platform>, where the platform is one of ios, macos, maccatalyst, tvos, watchos or visionos.

The Makefile is where the supported simulators are pinned

The Makefile is the best documentation in the repository for what the project is tested against. It opens with a help goal as the default, and the configuration section pins the Xcode scheme to TPPDF, offers an optional TEST_FILTER variable for narrowing tests on macOS, and then sets the simulator target for each platform. The iOS simulator OS defaults to 26.2 and can be overridden through IOS_SIMULATOR_OS, with the device name defaulting to iPhone 17 Pro and overridable through IOS_DEVICE_NAME. The tvOS target defaults to the same 26.2 simulator OS on an Apple TV 4K, third generation, device. The visionOS target uses 26.2 with an Apple Vision Pro, and the watchOS target uses 26.2 as well, with the device name listed as an override point. The pattern tells you two things. The project is tested against current Apple tooling rather than a historical baseline, and the whole matrix is configurable through environment variables, which is what you would want in a continuous integration setup that runs on a different machine.

A side project, and the README says so

The Communication section is the part of this README that a buyer should read first, because it sets the maintenance expectation in the maintainer's own words. TPPDF is an open source side project of techprimate, and since the team is currently working on several other projects, there is only limited time for fixing bugs and enhancing TPPDF. The consequence is stated as a request rather than a warning, since any issue reporting and especially pull requests are very welcome. Professional support is offered through the maintainer's contact details on Twitter and on the techprimate website, mainly for custom or high-priority requests, and the README says no consulting pricing will be published for now. Everything else routes to the issue tracker, with a bug report template for help requests and for bugs, a feature request template, and pull requests for contributions. That is a candid position, and it is better to know it before you depend on the library than after a release goes wrong.

Repository, releases and the licence

The tree shows a conventional Swift package with more than the minimum around it. There is Package.swift, a Source directory, Tests, a Documentation directory, an Example directory holding Example.yml with Resources, Sources and UITests, and a Makefile. Then there is the tooling layer, with a .swiftlint.yml and .swiftformat for Swift style, a .pre-commit-config.yaml, a Dangerfile.swift for pull request review, a dprint.json for other formatting, a .jazzy.yaml for the generated documentation, a .ruby-version and a Gemfile with a lock file for those tools, a Brewfile, renovate.json for dependency updates, and an AGENTS.md. The releases are infrequent by design, with 2.6.0 on 2024-07-09, 2.6.1 on 2024-11-11, and a 3.0.0 alpha tagged on 2025-12-26, so the stable line has not moved in a while while a major version sits in alpha. The last push was on 2026-10-18 and the repository is not archived. The licence is MIT. The README also carries a list of apps built with TPPDF, which is a decent proxy for the range of documents people produce with it, from chat history exports to a bug journal and an energy tracker.

Editorial conclusion

TPPDF fits an iOS or macOS team that needs to produce a document inside an app, a receipt, a report or an export, and that would rather describe a layout in commands than assemble a PDF by hand. It is the wrong choice if you need a document engine with a template language, because the layout is expressed in Swift calls rather than in markup, and it is a poor fit if you need a maintained release cadence, since the newest tagged versions are 2.6.1 from 2024 and a 3.0.0 alpha from the end of 2025. Before you adopt it, read the usage documentation in the Documentation directory, and check the maintenance note in the README, because the author asks for pull requests to cover the gaps a small team cannot.

Frequently asked questions

Official sources

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