Skip to content
PDF Oxide

Biblioteca PDF para Node.js — PDF Oxide

PDF Oxide es la biblioteca PDF más rápida para Node.js: 0,8 ms promedio por página, 5× más rápida que PyMuPDF, 15× más rápida que pypdf y 100 % de éxito en 3 830 PDFs. Un solo paquete para extraer, crear y editar PDFs — con tipos de TypeScript incluidos. Licencia MIT / Apache-2.0.

¿Ejecutas en navegador, Deno, Bun o Cloudflare Workers? Usa el build WASM — misma API, sin binarios nativos. El addon nativo de esta página es para Node.js y Electron.

Instalación

npm install pdf-oxide

Requisitos: Node.js 18 o superior. Sin dependencias de sistema. Sin toolchain de Rust. Los addons .node precompilados para Linux (glibc + musl) x64/arm64, macOS x64/arm64 y Windows x64/arm64 se descargan automáticamente vía optionalDependencies por plataforma — nada se compila al instalar.

Abrir un PDF

JavaScript

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("research-paper.pdf");
console.log(`Pages: ${doc.getPageCount()}`);

const { major, minor } = doc.getVersion();
console.log(`PDF version: ${major}.${minor}`);

doc.close();

TypeScript

import { PdfDocument } from "pdf-oxide";

const doc: PdfDocument = new PdfDocument("research-paper.pdf");
const pageCount: number = doc.getPageCount();
const { major, minor }: { major: number; minor: number } = doc.getVersion();
console.log(`${pageCount} pages, PDF ${major}.${minor}`);
doc.close();

En Node.js 22+ puedes usar using para liberar recursos automáticamente:

{
  using doc = new PdfDocument("report.pdf");
  const text = doc.extractText(0);
} // se invoca doc.close() automáticamente

API de páginas

Desde v0.3.34 PdfDocument es iterable y doc.page(i) devuelve un PdfPage con width / height / rotation en caché, además de métodos de extracción por página.

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("paper.pdf");
for (const page of doc) {
  console.log(`Page ${page.index}: ${page.width}x${page.height} (rotation ${page.rotation})`);
  const md = page.markdown();
  const tables = page.tables();       // filas y celdas con bboxes
}
doc.close();

Indexación: doc.page(0), doc.page(-1) (última página). Métodos de página: text(), markdown(), html(), plainText(), words(), lines(), tables(), images(), paths(), annotations(), fonts(), search(query, caseSensitive).

Extracción de texto

Una sola página

JavaScript

const { PdfDocument } = require("pdf-oxide");

const doc = new PdfDocument("report.pdf");
const text = doc.extractText(0);
console.log(text);
doc.close();

TypeScript

import { PdfDocument } from "pdf-oxide";

const doc: PdfDocument = new PdfDocument("report.pdf");
const text: string = doc.extractText(0);
console.log(text);
doc.close();

Todas las páginas

const doc = new PdfDocument("book.pdf");
const pageCount = doc.getPageCount();

for (let i = 0; i < pageCount; i++) {
  console.log(`--- Page ${i + 1} ---`);
  console.log(doc.extractText(i));
}

doc.close();

Extracción asíncrona

Cada método síncrono tiene su versión *Async, que corre en el pool de hilos de libuv. Úsalas en handlers HTTP y otro código de servidor concurrente para que la extracción no bloquee el event loop.

const { PdfDocument } = require("pdf-oxide");

async function extract(path) {
  const doc = new PdfDocument(path);
  try {
    return await doc.extractTextAsync(0);
  } finally {
    doc.close();
  }
}

Consulta la guía async para patrones como Promise.all repartiendo páginas.

Extracción estructurada

Datos a nivel de carácter y de span con posiciones y metadatos de fuente:

const chars = doc.extractChars(0);
for (const ch of chars.slice(0, 10)) {
  console.log(`'${ch.char}' at (${ch.x.toFixed(1)}, ${ch.y.toFixed(1)}) ` +
              `size=${ch.fontSize.toFixed(1)} font=${ch.fontName}`);
}

const spans = doc.extractSpans(0);
for (const span of spans) {
  console.log(`"${span.text}" font=${span.fontName} size=${span.fontSize}`);
}

Extracción por palabra y línea con segmentación ajustable:

const words = doc.extractWords(0);
const lines = doc.extractTextLines(0, { wordGapThreshold: 2.5, lineGapThreshold: 1.2 });

Conversión a Markdown

JavaScript

const md = doc.toMarkdown(0, { detectHeadings: true });
console.log(md);

// Todas las páginas
const allMd = doc.toMarkdownAll();

TypeScript

const md: string = doc.toMarkdown(0, { detectHeadings: true });
const allMd: string = doc.toMarkdownAll();

Conversión a HTML

const html = doc.toHtml(0);
const allHtml = doc.toHtmlAll();

Extracción de imágenes

const { writeFileSync } = require("fs");

const doc = new PdfDocument("brochure.pdf");
const images = doc.extractImages(0);

for (const [i, img] of images.entries()) {
  console.log(`Image ${i}: ${img.width}x${img.height} ${img.format} (${img.data.length} bytes)`);
  writeFileSync(`image_${i}.${img.format}`, img.data);
}

doc.close();

Las imágenes de PDFs con color indexado se expanden automáticamente a RGB, incluyendo paletas indexadas de 1/2/4/8 bpc con espacios base RGB, Grises o CMYK.

Abrir desde bytes

Abre un PDF desde bytes en memoria — útil cuando descargas desde S3, HTTP o bases de datos:

const { PdfDocument } = require("pdf-oxide");
const { readFileSync } = require("fs");

const bytes = readFileSync("document.pdf");
const doc = PdfDocument.openFromBytes(bytes);
const text = doc.extractText(0);
doc.close();

PDFs con contraseña

const doc = PdfDocument.openWithPassword("confidential.pdf", "secret");
const text = doc.extractText(0);
doc.close();

También puedes autenticarte después de abrir el archivo:

const doc = new PdfDocument("confidential.pdf");
if (doc.authenticate("secret")) {
  console.log(doc.extractText(0));
}
doc.close();

Los PDFs AES-256 (V=5, R=6) están totalmente soportados, incluyendo captions de widgets push-button y cachés de objetos invalidados correctamente tras autenticación tardía.

Creación de PDFs

La clase Pdf ofrece métodos de fábrica para crear PDFs a partir de varios formatos de origen.

Desde Markdown

const { Pdf } = require("pdf-oxide");
const { writeFileSync } = require("fs");

const pdf = Pdf.fromMarkdown("# Hello World\n\nThis is a PDF.");
writeFileSync("output.pdf", pdf.toBytes());

Desde HTML

const pdf = Pdf.fromHtml("<h1>Invoice</h1><p>Amount due: $42.00</p>");
writeFileSync("invoice.pdf", pdf.toBytes());

Desde texto plano

const pdf = Pdf.fromText("Plain text document.\n\nSecond paragraph.");
writeFileSync("notes.pdf", pdf.toBytes());

Desde imágenes

const pdf = Pdf.fromImage("scan.jpg");
writeFileSync("scan.pdf", pdf.toBytes());

Búsqueda

const doc = new PdfDocument("manual.pdf");

// Buscar en todas las páginas
const results = doc.searchAll("configuration", { caseSensitive: false });
for (const r of results) {
  console.log(`Page ${r.page}: "${r.text}" at (${r.x.toFixed(0)}, ${r.y.toFixed(0)})`);
}

// Buscar en una sola página
const pageResults = doc.searchPage(0, "configuration");
doc.close();

Para búsquedas en streaming sobre documentos grandes, usa SearchStream:

const { PdfDocument, SearchStream, SearchManager } = require("pdf-oxide");

const doc = new PdfDocument("large.pdf");
const manager = new SearchManager(doc);
const stream = new SearchStream(manager, "invoice");

stream.on("data", (r) => console.log(`page ${r.pageIndex + 1}: ${r.text}`));
stream.on("end", () => doc.close());

Detalles en la guía de Node.js streams.

Edición

Usa DocumentEditor para metadatos, operaciones de página, anotaciones y campos de formulario:

const { DocumentEditor } = require("pdf-oxide");

const editor = DocumentEditor.open("document.pdf");

// Metadatos
editor.setTitle("Updated Title");
editor.setAuthor("Jane Doe");

// Operaciones de página
editor.rotatePage(0, 90);
editor.deletePage(5);
editor.movePage(2, 0);

// Formularios
editor.setFormFieldValue("employee.name", "Jane Doe");
editor.flattenForms();

editor.save("edited.pdf");
editor.close();

OCR

Activa la feature ocr al instalar para habilitar OCR sobre páginas escaneadas:

npm install pdf-oxide --build-from-source -- --features ocr

const { PdfDocument, OcrEngine } = require("pdf-oxide");

const doc = new PdfDocument("scanned.pdf");
const ocr = new OcrEngine();

if (ocr.pageNeedsOcr(doc, 0)) {
  const text = ocr.extractText(doc, 0);
  console.log(text);
}

ocr.close();
doc.close();

Más recetas en la guía de OCR.

Seguridad entre hilos

PdfDocument es Send + Sync — puedes compartir un único documento entre workers para leer páginas en paralelo. Los métodos *Async lo hacen automáticamente usando el pool de hilos de libuv; para patrones manuales, revisa concurrencia.

Manejo de errores

Todos los métodos lanzan excepción si algo falla:

const { PdfDocument } = require("pdf-oxide");

try {
  const doc = new PdfDocument("document.pdf");
  const text = doc.extractText(0);
  doc.close();
} catch (err) {
  console.error(`Extraction failed: ${err.message}`);
}

Próximos pasos