printwell

Early Development - This project is in active early development. APIs may change, and some features are incomplete. Some commercial features may become free in future releases. Feedback and contributions welcome!

High-fidelity HTML to PDF conversion using Chromium's rendering engine.

Features

• Rendering: Full HTML5/CSS3 support via Chromium's Blink engine
• Large Documents: Automatic chunking for documents >50MB with parallel rendering
• Watermarks: Text and image overlays with positioning and opacity control
• Bookmarks: Table of contents and navigation structure
• Annotations: Highlights, sticky notes, and geometric shapes

Crates

Quick Start

use printwell::{Converter, PdfOptions, RenderOptions, PageSize};

#[tokio::main]
async fn main() -> printwell::Result<()> {
    let converter = Converter::new()?;

    let pdf = converter.html_to_pdf(
        "<h1>Hello, World!</h1>",
        &RenderOptions::default(),
        &PdfOptions::builder()
            .page_size(PageSize::A4)
            .print_background(true)
            .build(),
    ).await?;

    pdf.write_to_file("output.pdf")?;
    Ok(())
}

CLI Usage

# Convert HTML file
printwell convert input.html -o output.pdf

# Convert URL
printwell convert https://example.com -o output.pdf

# Convert with custom page size and margins
printwell convert input.html -o output.pdf --page-size Letter --margin 20mm

# Add watermark
printwell watermark input.pdf -o output.pdf --text "CONFIDENTIAL" --opacity 0.3

# Add bookmarks
printwell bookmarks input.pdf -o output.pdf --add "Chapter 1:1" --add "Chapter 2:5"

# Add annotations
printwell annotate input.pdf -o output.pdf --highlight 1:100:700:200:20

# Batch convert multiple files
printwell convert-batch *.html -o output_dir/ --workers 4

Bindings

Node.js (npm)

import { Converter, htmlToPdf } from 'printwell';

// Simple conversion
const result = await htmlToPdf('<h1>Hello, World!</h1>');
result.writeToFile('output.pdf');

// With options
const converter = new Converter();
const pdf = await converter.htmlToPdf(html, {}, {
    pageSize: 'A4',
    printBackground: true,
});

Python (PyPI)

from printwell import Converter, html_to_pdf

# Simple conversion
result = html_to_pdf('<h1>Hello, World!</h1>')
result.write_to_file('output.pdf')

# With options
converter = Converter()
pdf = converter.html_to_pdf(html, pdf_options=PdfOptions(
    page_size=PageSize.A4,
    print_background=True,
))

Requirements

• Rust: 1.92.0 or later (MSRV)
• Docker: Required for building the native library

Architecture

Printwell uses a two-layer architecture:

1. Native library (libprintwell_native.so) - Shared library with C++ code + Chromium (blink, skia, pdfium), built with ThinLTO
2. Rust layer - High-level API that links against the native library dynamically

The native library (~50MB) is pre-built and stored in the repo, so most contributors don't need to build Chromium.

Note: We are working on a Chromium CI workflow to build and distribute the native library separately from the repo. This will reduce clone sizes and improve the contributor experience.

Building

For Contributors (without Chromium)

Contributors can build and test without cloning/building Chromium:

# Build CLI (links against pre-built libprintwell_native.so)
cargo build -p printwell-cli --release

# Build bindings
cargo xtask bindings node --release
cargo xtask bindings python --release

# Run tests
cargo xtask bindings test

For Core Developers (with Chromium)

Core developers who need to modify C++ code or update Chromium:

# Setup build environment (one-time)
cargo xtask init

# Fetch Chromium source (~30GB)
cargo xtask chromium fetch

# Sync Chromium dependencies
cargo xtask chromium sync

# Build native library (libprintwell_native.so)
cargo xtask build --release

# After C++ changes, commit the updated native library:
git add native/linux-x64/libprintwell_native.so
git commit -m "Update pre-built native library"

Testing

# Run binding tests
cargo xtask bindings test

# Run end-to-end tests
cargo xtask e2e

# Run lints
cargo xtask lint

License

AGPL-3.0 - See LICENSE for details.