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
• 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
• Git LFS: Required for pre-built native libraries

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 via Git LFS, so most contributors don't need to build Chromium.

Building

For Contributors (without Chromium)

Contributors can build and test without cloning/building Chromium:

# Install Git LFS and pull pre-built native library
git lfs install
git lfs pull

# 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.