Skip to content

README.md

Latest commit

 

History

History
303 lines (217 loc) · 6.94 KB

README.md

File metadata and controls

303 lines (217 loc) · 6.94 KB

WhatsApp2PDF (Node.js)

node npm version npm downloads License: MIT

Transform WhatsApp messages into beautiful, printable PDF documents (with TypeScript support).

Convert WhatsApp chat exports (Android & iOS) into professional PDF files with authentic WhatsApp styling, emoji support, themes, and media attachments. Perfect for preserving memories, creating archives, or sharing conversations.

🌟 Why WhatsApp2PDF?

  • 📱 Universal Support - Works with both Android and iOS exports
  • 🎨 Beautiful Themes - Light & Dark WhatsApp-authentic themes included
  • 🔒 Privacy First - Optional privacy mode to hide sensitive information
  • 🖼️ Media Included - Optionally embed images in your PDF
  • 🌍 International - Full emoji and multi-language support (Chinese, Japanese, Korean)
  • ⚡ Lightning Fast - High-performance rendering for large chats
  • 🛠️ Developer Friendly - CLI and programmatic API
  • 📄 Professional Output - A4-sized PDFs ready to print or share

📦 Installation

Global (Recommended for CLI)

npm install -g whatsapp2pdf

Local (For Node.js projects)

npm install whatsapp2pdf

Requirements: Node.js 18.7 or higher

🚀 Quick Start

📋 CLI Usage

# Basic conversion
whatsapp2pdf chat.zip

# With options
whatsapp2pdf chat.zip -o my-chat.pdf --theme dark --images

# Full help
whatsapp2pdf --help

📋 CLI Options

Option Description Default
--list-themes Display built‑in themes -
-o, --output <file> Output PDF path Auto-generated
-u, --main-user <name> Set right‑side sender First contact
-p, --privacy Hide contact names true
-i, --images Include attachments true
-t, --theme <name> Theme: light / dark light
--theme-path <json> Load custom theme JSON -
-s, --start <YYYY-MM-DD> Filter start date -
-e, --end <YYYY-MM-DD> Filter end date -
-k, --keyword <word> Keyword filter -
-v, --verbose Debug info -
-h, --help Show help -
-V, --version Show version -

🛠️ Programmatic Usage

const WhatsApp2PDF = require("whatsapp2pdf");

// Simple conversion
await WhatsApp2PDF("./chat.zip")
    .output("chat.pdf")
    .convert();

// Advanced options
await WhatsApp2PDF("./chat.zip")
    .theme("dark")
    .mainUser("Your Name")
    .seal()              // Privacy mode
    .images()            // Include media
    .searchDate("2024-01-01", "2024-12-31")
    .output("chat.pdf")
    .convert();

🛠️ Methods

.output(path) - Set output PDF path
.theme(name|path|object) - Set theme
.mainUser(name) - Set right-side sender
.seal(enable) - Partially hide contact names
.images(enable) - Include media
.searchDate(start, end) - Filter by date
.searchKeyword(keyword) - Filter by keyword
.verbose(enable) - Enable debug logging
.parse() - Parse without generating PDF
.convert() - Generate PDF

🛠️ Static Methods

WhatsApp2PDF.listThemes() - Get available themes

🎨 Features

Multiple Themes

  • ✅ Built-in Light & Dark themes
  • ✅ Custom theme support (JSON)
  • ✅ WhatsApp-authentic styling

Privacy Mode

  • 🔒 Partially hide contact names (e.g., "Alice" → "Al***ce")
  • 🔒 Chat messages remain visible
  • 🔒 Perfect for demos and presentations

Search & Filter

  • 🔍 Filter by date range
  • 🔍 Search by keywords
  • 🔍 Extract specific conversations

Media Support

  • 🖼️ Images (JPG, PNG, GIF, WebP, HEIC, AVIF)

Multi-Language Support

  • 🌍 Full emoji rendering
  • 🇨🇳 Chinese (Simplified & Traditional)
  • 🇯🇵 Japanese (Hiragana, Katakana, Kanji)
  • 🇰🇷 Korean (Hangul)

⚙ Architecture Diagram

[ CLI / API ]
      |
      v
+----------------+
|   Parser       |
|  chat.zip/txt  |
+----------------+
      |
      v
+----------------+
|  Renderer      |
| PDFKit + sharp |
+----------------+
      |
      v
   output.pdf

🎨 Themes

Built-in Themes

whatsapp2pdf --list-themes

Light Theme

{
  "background_color": "#EAE6DF",
  "background_image": "./light.png",
  "bubble": {
    "color": "#D9FDD3",
    "color_other": "#FFFFFF"
  },
  "fonts": {
    "color": "#111B21",
    "family": "Helvetica",
    "size": 14
  }
}

Dark Theme

{
  "background_color": "#0A1014",
  "background_image": "./dark.png",
  "bubble": {
    "color": "#144D37",
    "color_other": "#233138"
  },
  "fonts": {
    "color": "#F7F8FA",
    "family": "Helvetica",
    "size": 14
  }
}

Custom Themes

Theme JSON supports:

  • background_color
  • background_image (file / URL / base64)
  • bubble styles
  • fonts
  • layout margins
  • watermark

Use with:

whatsapp2pdf chat.zip --theme-path ./my-theme.json

🧪 Testing

npm test

🐛 Troubleshooting

Memory Issues (Large Chats)

node --max-old-space-size=4096 $(which whatsapp2pdf) chat.zip

Emoji Not Rendering

Install Noto Emoji font in assets/fonts/NotoEmoji.ttf

No Chat File Found

Ensure ZIP contains a file starting with "WhatsApp Chat" and ending with .txt

📊 Performance

  • ⚡ Handles chats with 50K+ messages
  • 🖼️ Processes hundreds of images
  • 📦 Optimized memory usage
  • 🚀 Fast multi-page rendering

🤝 Contributing

Contributions welcome! Please see our GitHub repository.

📄 License

MIT © stlong5

⭐ Support This Project

If WhatsApp2PDF saves you time or helps preserve your memories:

🔗 Links

Made with ❤️ for preserving memories