Skip to content
pdf-textlayer
Esc
↑↓navigate↵open⌘Jpreview
On this page

Node.js

The pdf-textlayer Node.js API — makeSearchablePdf, writeTextLayer, addTextLayer, loadPages, their TypeScript types, and error codes.

npm install pdf-textlayer
pnpm add pdf-textlayer
yarn add pdf-textlayer
bun add pdf-textlayer
nub add pdf-textlayer
aube add pdf-textlayer

Node.js 20 or newer, ESM and CommonJS, with TypeScript types included. A prebuilt native module is installed for macOS (arm64, x64), Linux (x64 and arm64 with glibc, x64 with musl), and Windows (x64, arm64); nothing is compiled on install. Writes run on the libuv thread pool, so they never block the event loop.

import { makeSearchablePdf } from "pdf-textlayer";

const stats = await makeSearchablePdf("input.pdf", "parsed.json", "output.pdf", {
  minConfidence: 0.5,
});
const { makeSearchablePdf } = require("pdf-textlayer");

makeSearchablePdf("input.pdf", "parsed.json", "output.pdf").then(console.log);

Functions

makeSearchablePdf

function makeSearchablePdf(
  input: string,
  source: Source | ParsedPage[],
  output: string,
  options?: MakeSearchableOptions,
): Promise<Stats>;

Reads OCR JSON with an adapter and writes the searchable PDF. source is a path (string or URL) to a JSON file, or the already-parsed document. It may also be an array of pages, in which case adapter is ignored.

writeTextLayer

function writeTextLayer(
  input: string,
  pages: ParsedPage[],
  output: string,
  options?: Options,
): Promise<Stats>;

Writes the PDF from boxes you already have. Pages not listed, or left with no drawable boxes, are copied unchanged.

addTextLayer

function addTextLayer(
  pdf: Uint8Array,
  pages: ParsedPage[],
  options?: Options,
): Promise<{ pdf: Buffer; stats: Stats }>;

Same as writeTextLayer for a PDF held in memory, such as an upload or an object from storage.

import { readFile } from "node:fs/promises";
import { addTextLayer, loadPages } from "pdf-textlayer";

const pages = await loadPages("parsed.json");
const { pdf, stats } = await addTextLayer(await readFile("scan.pdf"), pages);

loadPages

function loadPages(source: Source, options?: { adapter?: Adapter }): Promise<ParsedPage[]>;

Resolves to the pages an adapter reads from OCR JSON, to inspect or edit before writing. Pages without OCR boxes are omitted, and malformed pages and items are skipped.

Types

interface TextBox {
  text: string;
  x: number;
  y: number;
  width: number;
  height: number;
  confidence?: number; // 0–1, default 1
  rotation?: number; // degrees counter-clockwise, default 0
}

interface ParsedPage {
  pageNumber: number; // 1-indexed page of the input PDF
  boxes: TextBox[];
}

type FontName = "helv" | "tiro" | "cour";
type Adapter = "liteparse";
type Source = string | URL | Record<string, unknown>;

interface Options {
  minConfidence?: number; // default 0
  font?: FontName; // default "helv"
  sanitizeUnsupported?: boolean; // default true
}

interface MakeSearchableOptions extends Options {
  adapter?: Adapter; // default "liteparse"
}

interface Stats {
  pages: number; // pages in the document
  ocrPages: number[]; // 1-indexed pages that received a text layer
  itemsDrawn: number; // boxes drawn across all pages
}

Boxes use PDF points with (x, y) the top-left corner on the displayed page; see Coordinates. The options match the Python options field for field.

Errors

Every function returns a promise that rejects with an Error whose code names what went wrong. Nothing is written when it rejects.

code Meaning
ENOENT The input PDF or the JSON file does not exist.
EIO Another file error, such as an unwritable output path.
ERR_INVALID_PDF The input is not a readable PDF, or it is encrypted.
ERR_INVALID_ARG_VALUE An unknown adapter or font, or JSON that does not parse.
try {
  await makeSearchablePdf("scan.pdf", "parsed.json", "out.pdf");
} catch (error) {
  if (error.code === "ERR_INVALID_PDF") {
    // skip files that are not PDFs, or are encrypted
  }
}

Was this page helpful?