pdfuse-core

pdfuse-core is a small, headless JavaScript / TypeScript library for merging PDF files in the browser. It builds on pdf-lib and gives you typed helpers to load uploaded PDFs, read page counts, and merge selected pages from multiple documents into one downloadable PDF (as a Uint8Array).

Use it in React, Vue, Svelte, or vanilla apps where users pick files with <input type="file"> and you want client-side PDF merge without a server.

Features

• Merge PDF pages from multiple sources in a custom order
• Load PDF from a File and get a pdf-lib PDFDocument plus total page count
• TypeScript types included (UploadedPDF, PageSelectionKey, etc.)
• ESM and CommonJS builds (import / require)
• Tree-shakeable (sideEffects: false)

Installation

npm install pdfuse-core

pnpm add pdfuse-core

yarn add pdfuse-core

Peer environment: loadPdfDocument uses the browser File and FileReader APIs. Use it in environments that provide those (typical browser or compatible runtimes). The merge helper only needs the in-memory PDFDocument instances you already loaded.

Quick start

1. Load a PDF from a file input

import { loadPdfDocument } from "pdfuse-core";

async function onFileSelected(file: File) {
  const { pdfDoc, totalPages } = await loadPdfDocument(file);
  console.log(totalPages, pdfDoc);
}

2. Merge selected pages from several PDFs

Each uploaded PDF is represented as an UploadedPDF: metadata plus the loaded pdf-lib document. PageSelectionKey picks a zero-based page from a PDF by its index in your array.

import { loadPdfDocument, mergeSelectedPages } from "pdfuse-core";
import type { UploadedPDF, PageSelectionKey } from "pdfuse-core";

const files: File[] = /* from input or drop zone */;

const pdfs: UploadedPDF[] = await Promise.all(
  files.map(async (file, i) => {
    const { pdfDoc, totalPages } = await loadPdfDocument(file);
    return {
      id: `doc-${i}`,
      file,
      pdfDoc,
      totalPages,
    };
  }),
);

// Order matters: first page of first PDF, then page 3 of second PDF, etc.
const selectedOrder: PageSelectionKey[] = [
  { pdfIndex: 0, pageIndex: 0 },
  { pdfIndex: 1, pageIndex: 2 },
];

const pdfBytes: Uint8Array = await mergeSelectedPages(pdfs, selectedOrder);

// Example: trigger download in the browser
const blob = new Blob([pdfBytes], { type: "application/pdf" });
const url = URL.createObjectURL(blob);
const a = Object.assign(document.createElement("a"), { href: url, download: "merged.pdf" });
a.click();
URL.revokeObjectURL(url);

API

| Export | Description | |--------|-------------| | isPdfFile(file) | Returns true if the File looks like a PDF (MIME type or .pdf extension). | | loadPdfDocument(file) | Loads a PDF from a File; returns { pdfDoc, totalPages }. Throws if not a PDF, unreadable, or has no pages. Uses ignoreEncryption: true when loading. | | mergeSelectedPages(pdfs, selectedOrder) | Creates a new PDF containing the chosen pages in order; returns Uint8Array. Skips invalid indices safely. |

Types

| Type | Purpose | |------|---------| | UploadedPDF | id, file, pdfDoc (pdf-lib), totalPages | | PageSelectionKey | pdfIndex (into the pdfs array), pageIndex (0-based page) | | LoadedPDF | id, pdfDoc, totalPages (no File) | | PageSelection | Alternative shape: one LoadedPDF plus pages: number[] |

Types re-export PDFDocument usage via pdf-lib; advanced edits can use the returned pdfDoc with pdf-lib directly.

Requirements

• Node.js ≥ 18 (for tooling / SSR setups that consume the package)
• Runtime: loadPdfDocument expects File + FileReader (browser-style APIs)

Related

• Full app: PDFuse — merge PDFs in the browser
• Source (monorepo): github.com/mahabeer-dev/PDFuse (packages/core)

License

MIT