pdf-lib: возможности, ограничения и актуальный статус библиотеки

pdf-lib — не просмотрщик и не настольный PDF-редактор, а библиотека на TypeScript/JavaScript, которую разработчик подключает к своему приложению. Её сильная сторона — программное создание PDF и изменение уже существующих документов прямо в Node.js, браузере, Deno или React Native без обязательного внешнего сервиса. При выборе в 2026 году важен контекст поддержки: официальный пакет pdf-lib по-прежнему опубликован и репозиторий не архивирован, однако стабильная версия 1.17.1 вышла 6 ноября 2021 года, а основная ветка проекта не получала новых продуктовых релизов с тех пор. Это делает библиотеку полезной для проверенных сценариев, но требует более строгой фиксации версии и собственных совместимых тестов.

Скачать pdf-lib

Безопасный базовый путь — устанавливать пакет с точным именем pdf-lib через npm или Yarn либо брать исходный код из официального Hopding/pdf-lib. Для npm используется npm install pdf-lib, для Yarn — yarn add pdf-lib. Текущая опубликованная версия — 1.17.1. В production разумно фиксировать проверенную версию и lock-файл, чтобы сборка оставалась воспроизводимой.

Для браузера без сборщика официальный README описывает UMD-сборки через unpkg и jsDelivr и рекомендует указывать конкретную версию в CDN-адресе. Загрузка JavaScript из CDN не означает автоматическую отправку PDF на сервер pdf-lib: передачу файлов определяет код приложения.

Не путайте официальный пакет с форками и похожими именами. @adnsistemas/pdf-lib и @pdfme/pdf-lib имеют собственные ветки и версии; react-native-pdf-lib — отдельный проект. Пакет pdf-lib-enhanced не является официальным продолжением: в мае 2026 года GitHub Advisory Database пометила его как вредоносный. Проверяйте точное имя pdf-lib и связь с Hopding/pdf-lib.

Что такое pdf-lib

pdf-lib создавался как универсальный JavaScript-инструмент для тех случаев, когда приложение должно не только сгенерировать новый PDF, но и открыть существующий документ, добавить или удалить страницы, дорисовать содержимое, заполнить форму или перенести страницы в другой файл. Официальное позиционирование формулируется как создание и изменение PDF в любой современной JavaScript-среде. Исходный код написан на TypeScript, пакет поставляет типы и несколько вариантов сборки, включая CommonJS, ES-модули и UMD.

Разработчиком в метаданных пакета указан Andrew Dillon. Репозиторий публичный, распространяется по MIT License и на дату проверки не помечен как archived или disabled. Однако это не следует интерпретировать как активный цикл разработки: версия 1.17.1 остаётся последней с ноября 2021 года. Правильное описание статуса — библиотека доступна и продолжает использоваться, но официальная линия давно не обновляется и не даёт современного темпа исправлений, характерного для активно поддерживаемых зависимостей.

pdf-lib также важно отделять от PDF-просмотрщиков. Она не показывает окно с документом, не содержит панели миниатюр, меню печати или визуального редактора. Если конечному пользователю нужен просмотр, приложение должно использовать браузер, отдельный viewer вроде PDF.js или настольную программу. В этом смысле pdf-lib и Sumatra PDF решают разные уровни одной задачи: pdf-lib изменяет байты документа программно, а Sumatra PDF предназначена для чтения и визуальной проверки готового файла.

Хронология развития и поддержки

Проект появился в 2017 году и к ветке 1.x перешёл на более высокий уровень API: асинхронные PDFDocument.create и PDFDocument.load, прямые операции с PDFPage, формами и ресурсами. Версия 1.17.1 добавила исправления форм и ключей ресурсов, а также улучшение использования памяти.

Ключевая дата для выбора сегодня — 6 ноября 2021 года, когда опубликована 1.17.1. После этого официальная npm-линия не получила новой версии, а основная ветка Hopding/pdf-lib не показывает продолжения регулярной продуктовой разработки. Репозиторий при этом не архивирован, Issues и Discussions доступны. Поэтому pdf-lib корректнее считать доступной, но давно не обновлявшейся зависимостью, а не продуктом с активным релизным циклом.

Современные форки могут включать шифрование, инкрементальное сохранение и другие функции, отсутствующие в оригинальной 1.17.1. Переход на них — смена зависимости с отдельным владельцем и рисками совместимости, а не обычное обновление «до pdf-lib 2.x».

Основные функции pdf-lib

Создание документов и управление страницами

PDFDocument.create создаёт новый документ, а PDFDocument.load открывает существующий PDF из Uint8Array, ArrayBuffer, Base64 или data URI. Можно добавлять, вставлять и удалять страницы, получать их индексы и копировать выбранные страницы между документами через copyPages. Это подходит для сборки пакетов, извлечения диапазонов и перестановки листов без ручного GUI.

embedPage и embedPdf решают другую задачу: исходная PDF-страница становится графическим ресурсом, который можно масштабировать, обрезать заданной областью и рисовать на другой странице. Это удобно для шаблонов и компоновки, но не превращает страницу в набор редактируемых текстовых блоков.

Текст, изображения и векторная графика

На страницу можно добавлять текст, линии, прямоугольники, эллипсы и SVG-path, а также встраивать JPEG и PNG. API умеет измерять текст для расчёта верстки. SVG-path здесь не равен импорту полноценного SVG-документа с CSS и фильтрами.

Стандартные PDF-шрифты работают без отдельной зависимости. Для собственных шрифтов нужен @pdf-lib/fontkit. Это критично для кириллицы: Helvetica по умолчанию использует WinAnsi, поэтому русский текст в формах и при рисовании лучше выводить явно встроенным шрифтом с нужными глифами.

PDF-формы

PDFForm работает с AcroForm: кнопками, флажками, dropdown, option list, radio group и текстовыми полями. Можно читать существующие поля, создавать новые, менять значения и обновлять appearance. Метод flatten переносит текущий вид полей в содержимое страницы и удаляет интерактивные поля и связанные аннотации.

После flatten форму уже нельзя редактировать обычным form API, поэтому до этой операции стоит сохранять интерактивную копию. XFA нельзя считать эквивалентно поддерживаемой: библиотека умеет обнаруживать XFA, но её основной high-level API ориентирован на AcroForm.

Метаданные, вложения и параметры просмотра

pdf-lib читает и задаёт Title, Author, Subject, Keywords, Creator, Producer, даты и язык. Viewer preferences позволяют задавать параметры вроде направления чтения, масштабирования при печати, duplex и диапазона страниц; конкретный viewer может часть таких предпочтений игнорировать.

PDFDocument.attach добавляет произвольный файл как вложение — это attachment, а не конвертация DOCX, XLSX или другого формата. Есть также document-level JavaScript. Его стоит использовать только осознанно: часть просмотрщиков блокирует PDF JavaScript политиками безопасности.

Чего библиотека не делает

Официальный README фиксирует важные ограничения: pdf-lib читает текст form fields, но не извлекает обычный текст страницы; меняет значения полей, но не предоставляет API для редактирования существующего page-text; не верстает HTML/CSS в PDF. OCR также отсутствует.

Зашифрованные PDF официально не поддерживаются. ignoreEncryption лишь подавляет проверку совместимости и не расшифровывает документ; модификации после такой загрузки могут завершиться ошибкой или некорректным результатом.

Интерфейс и удобство использования

У pdf-lib нет собственного графического интерфейса. Рабочий поток состоит из получения входных байтов, создания или загрузки PDFDocument, операций с PDFPage/PDFForm и сериализации через save. Для разработчика, знакомого с promises, Uint8Array и координатной моделью PDF, API достаточно последовательный; пользователю без JavaScript библиотека напрямую не подходит.

Высокоуровневые классы разделяют ответственность: PDFDocument — документ, PDFPage — геометрия и рисование, PDFForm — формы, PDFFont и PDFImage — ресурсы. Низкоуровневый context доступен, но требует знания структуры PDF и повышает риск несовместимого результата.

Документация и имена API англоязычные. Русский текст поддерживается не «языком интерфейса», а корректно встроенным шрифтом и его набором символов.

Есть ещё один практический порог: страницы адресуются индексами с нуля, а расположение контента задаётся числовыми координатами. pdf-lib не выполняет автоматическую «переверстку документа» как текстовый редактор, поэтому приложение само рассчитывает позиции, переносы и размеры элементов. Для шаблонных документов это предсказуемо, а для свободной офисной верстки потребует собственного layout-слоя.

Поддерживаемые форматы и совместимость

Основной вход и выход — PDF. load принимает Uint8Array, ArrayBuffer, Base64 или data URI, save возвращает Uint8Array, saveAsBase64 — строку. pdf-lib не является конвертером DOCX/XLSX/HTML в PDF.

Как ресурсы поддерживаются JPEG и PNG; страницы другого PDF можно копировать или встраивать. Произвольные файлы добавляются как attachments, но не становятся видимым содержимым. Пользовательские шрифты подключаются через fontkit. SVG поддерживается как path-данные, а не как полноценный веб-документ.

Официальный проект заявляет работу в Node, Browser, Deno и React Native и поставляет CommonJS, ES и UMD-сборки. Отдельной версии под Windows, macOS или Linux нет: совместимость определяется runtime и способом работы с файлами.

Отдельно стоит учитывать, чего нет на выходе: pdf-lib сохраняет PDF, но не рендерит страницу в PNG/JPEG и не выступает полноценным viewer. PNG и JPEG для неё — входные изображения для встраивания. Если приложению нужны превью страниц, thumbnail или растровый экспорт, эту часть обычно поручают PDF.js, системному рендереру или другому специализированному компоненту.

После генерации результат стоит открывать независимым viewer. Для визуальной проверки и ручной диагностики подойдёт, например, PDF-XChange Editor; это контроль готового файла, а не замена библиотеке в коде.

Производительность и стабильность

Официальный проект не публикует актуальные бенчмарки, поэтому нельзя честно обещать число страниц в секунду или максимальный размер файла. load получает PDF целиком как массив байтов, а save формирует новый Uint8Array; крупные документы требуют памяти одновременно на вход, разобранные объекты, ресурсы и выходной буфер.

В API есть parseSpeed и objectsPerTick. Документ миграции объясняет, что ParseSpeeds.Fastest может ускорить парсинг там, где допустима более длительная блокировка event loop, а objectsPerTick управляет периодическими уступками управления при сохранении. Это баланс отзывчивости и скорости, а не средство уменьшить объём PDF.

Версия 1.17.1 включала улучшение использования памяти, но библиотека давно не получала релизов. Поэтому стабильность нужно проверять на своих источниках: корпоративных формах, сканах, файлах с редкими объектами и большом количестве страниц. На сервере разумно ограничивать размер входа и параллелизм, в браузере — учитывать память вкладки.

Хороший регрессионный набор должен включать хотя бы обычный текстовый PDF, форму, многостраничный файл, документ с пользовательскими шрифтами и один максимально крупный типовой источник. Для каждого файла полезно проверять успешность load/save, число страниц, ключевые поля формы, размер результата и открытие минимум в одном независимом viewer. Такой набор важнее абстрактного бенчмарка, потому что основные риски pdf-lib связаны не только со скоростью, но и с разнообразием реальных PDF-структур.

Паспорт обратимости операций

У pdf-lib нет пользовательского Undo-стека. Пока объект PDFDocument живёт в памяти, приложение само решает, хранить ли предыдущую версию. После save единственным надёжным откатом является собственная копия исходных байтов или версия в системе хранения. Это особенно важно для flatten, удаления страниц и низкоуровневых правок через context.

Лицензирование и версии

Официальный pdf-lib распространяется по MIT License. Лицензия разрешает использование, копирование, изменение, объединение, публикацию, распространение, сублицензирование и продажу копий при сохранении уведомления об авторских правах и текста лицензии в соответствующих копиях или существенных частях программного обеспечения. Программа предоставляется без гарантий. Для коммерческого проекта отдельная платная лицензия pdf-lib не требуется.

У продукта нет разделения на Free, Pro, Enterprise, пробного периода, подписки или регистрации. Нет и облачного аккаунта pdf-lib, который нужно активировать для работы API. Затраты возникают на стороне вашего проекта: разработка интерфейса, инфраструктура, тестирование, возможные шрифтовые лицензии, поддержка и выбор альтернативы для функций, которых нет в pdf-lib.

Актуальная официальная линия заканчивается на 1.17.1. Пакеты с именами вроде @adnsistemas/pdf-lib имеют собственную нумерацию и не должны описываться как «pdf-lib 2.x». При аудите зависимости полезно проверять не только версию, но и точное имя пакета, владельца и URL репозитория: в JavaScript-экосистеме похожее название может вести к другому коду и другой модели поддержки.

MIT License не отменяет обычный supply-chain аудит. pdf-lib имеет собственные runtime-зависимости, а проект может дополнительно подключать fontkit, bundler и другие пакеты. Для корпоративной сборки разумно сохранять lock-файл, проверять происхождение пакетов и повторять аудит при любом изменении дерева зависимостей, даже если сама версия pdf-lib не меняется.

Системные требования

Проект не публикует таблицу минимальных версий Windows, macOS, Linux, CPU или RAM: pdf-lib запускается внутри JavaScript-runtime. В package.json 1.17.1 нет поля engines с официальным минимумом Node.js, поэтому такой номер нельзя придумывать.

Node.js и серверные среды

Пакет содержит CommonJS и ES-модульную сборку. Память зависит от размера и сложности PDF. Для собственных шрифтов устанавливается @pdf-lib/fontkit. Чтение с диска, лимиты процесса и параллелизм задаёт приложение.

Браузеры

README заявляет современные браузеры и UMD-сборки, скомпилированные до ES5, но свежей матрицы браузерных версий для 2026 года проект не ведёт. Совместимость следует подтверждать тестами в браузерах, поддерживаемых вашим продуктом.

Deno и React Native

Обе среды перечислены как поддерживаемые. Deno-документация содержит старый URL-import через CDN, поэтому для новых проектов лучше фиксировать версию и использовать актуальный механизм пакетов вашей версии Deno. React Native здесь означает JavaScript-пакет pdf-lib, а не отдельный react-native-pdf-lib.

Карта критических зависимостей

Эта карта показывает главный архитектурный плюс pdf-lib: её можно встроить в локальный или серверный процесс без обязательной отправки документов третьему сервису. Но приватность не возникает автоматически. Если ваше приложение само загружает PDF в API, CDN, объектное хранилище или аналитическую систему, именно эта архитектура определит маршрут данных. Для конфиденциального документа нужно проверять весь data-flow, а не только лицензию библиотеки.

Преимущества и недостатки pdf-lib

Плюсы и минусы

Создаёт новые PDF и действительно изменяет существующие документы, а не ограничивается генерацией с нуля.

Работает в нескольких JavaScript-средах: Node.js, браузере, Deno и React Native.

MIT License допускает коммерческое использование без подписки и платной редакции.

Есть высокоуровневые API для страниц, AcroForm, PNG/JPEG, встроенных PDF-страниц, шрифтов, вложений и метаданных.

Не требует аккаунта, облачного API или передачи файла разработчику библиотеки.

Поставляет TypeScript-типы и несколько форматов модулей.

Для многих операций достаточно одного JavaScript-пакета без нативного PDF-движка.

Минусы

Официальная версия 1.17.1 не обновлялась с ноября 2021 года, поэтому риск несовместимости и накопившихся edge cases выше, чем у активно развиваемой зависимости.

Нет полноценного редактирования существующего текста страницы и обычного text extraction.

Нет OCR и конвертации DOCX/XLSX/HTML в PDF как встроенной функции.

Шифрованные PDF официально не поддерживаются; ignoreEncryption не является расшифровкой.

Нет собственного viewer или GUI, поэтому конечный продукт требует отдельного интерфейса и визуальной проверки.

Для Unicode, включая кириллицу в формах, часто нужен собственный шрифт и @pdf-lib/fontkit.

Высокоуровневое сохранение сериализует документ в новый буфер; для больших файлов нужно заранее проектировать лимиты памяти.

Сравнение с аналогами

Для генерации с нуля jsPDF и PDFKit заслуживают отдельной оценки, особенно из-за более активных современных релизов. Для просмотра в веб-приложении PDF.js логичнее использовать рядом с pdf-lib. В Java-сервисе PDFBox даёт более широкий набор операций.

Настольные программы решают другой workflow. Для чтения готового результата можно ориентироваться на Adobe Acrobat Reader DC, а для ручной работы с офисными документами и экспортом — на LibreOffice. pdf-lib остаётся компонентом разработки.

Инструкция по установке

Node.js или проект со сборщиком

1. Откройте проект с работающим package manager и lock-файлом.

2. Установите npm install pdf-lib либо yarn add pdf-lib.

3. Проверьте, что установлен именно pdf-lib версии 1.17.1 из ожидаемого registry.

4. Импортируйте PDFDocument и выполните минимальный сценарий создания или загрузки PDF.

5. Сохраните байты и откройте результат независимым viewer — это проверит импорт, запись и базовую совместимость.

Собственный шрифт и кириллица

1. Установите @pdf-lib/fontkit и зарегистрируйте его в PDFDocument.

2. Встройте шрифт с кириллическими глифами и используйте его при рисовании или обновлении appearance формы.

3. Сохраните контрольный PDF и проверьте русский текст в нескольких viewer, если документ идёт внешним получателям.

Браузер без bundler

Официальный проект предлагает UMD через unpkg или jsDelivr. В production фиксируйте 1.17.1, а не «latest». Если политика безопасности запрещает сторонние скрипты, храните проверенную сборку в собственной инфраструктуре.

Удаление

Используйте npm uninstall pdf-lib или yarn remove pdf-lib; неиспользуемый @pdf-lib/fontkit удаляется отдельно. Сгенерированные PDF автоматически не удаляются. При UMD-подключении уберите script и локальные копии библиотеки из проекта.

Практические кейсы

Сборка одного PDF из нескольких источников

Цель. Собрать выбранные страницы нескольких PDF. Подготовка. Убедиться, что файлы не зашифрованы. Шаги. Загрузить источники, создать целевой PDFDocument, вызвать copyPages для нужных индексов, добавить страницы в требуемом порядке и сохранить. Проверка. Сверить количество, порядок и открыть начало, середину и конец. Ограничение. Копирование не выполняет OCR и не снимает шифрование.

Заполнение AcroForm и flatten

Цель. Заполнить форму и получить стабильный финальный файл. Подготовка. Знать имена полей и подготовить Unicode-шрифт для кириллицы. Шаги. Получить PDFForm, записать значения, обновить appearance, сохранить интерактивную версию, затем при необходимости выполнить flatten и сохранить финал отдельно. Проверка. Сверить значения и внешний вид. Ограничение. После flatten поля уже не редактируются как форма.

Штамп или служебная отметка

Цель. Добавить изображение и текст на существующую страницу. Подготовка. Иметь PNG/JPEG и понимать координаты. Шаги. Встроить изображение, выбрать страницу, вычислить её размер, нарисовать картинку и подпись, сохранить новый файл. Проверка. Контролировать положение и читаемость. Ограничение. Картинка подписи не является криптографической электронной подписью.

Генерация полностью в браузере

Цель. Создать документ без обязательной серверной обработки. Подготовка. Подключить зафиксированную версию pdf-lib и локальные ресурсы. Шаги. Создать PDFDocument, добавить контент, сохранить Uint8Array и сформировать Blob для открытия или загрузки. Проверка. Открыть Blob независимым viewer. Ограничение. Большой PDF потребляет память вкладки, а собственные сетевые запросы приложения остаются частью data-flow.

Изменение метаданных без визуальной правки страниц

Цель. Обновить Title, Author, Subject или Keywords, не рисуя новый контент. Подготовка. Сохранить исходный PDF и определить, какие поля должны измениться. Шаги. Загрузить документ, прочитать текущие метаданные, вызвать соответствующие set-методы и сохранить результат под новым именем. Проверка. Повторно открыть файл и прочитать поля API или свойства документа в viewer. Ограничение. По умолчанию загрузка может обновлять служебные Producer и ModificationDate; если сохранение исходных метаданных критично, нужно учитывать опцию updateMetadata при load и проверять итог явно.

Контроль перед сохранением и передачей

Не принимать ignoreEncryption за способ расшифровки.

Сверить количество, порядок и размеры страниц после структурных операций.

Для кириллицы проверить встроенный шрифт и отображение глифов.

Для форм решить, нужна интерактивная версия или flatten; при необходимости сохранить обе.

Проверить метаданные и открыть итог в независимом viewer.

Не путать картинку подписи с цифровой подписью и хранить исходный PDF до конца контроля.

Навигатор по сбоям

Часто задаваемые вопросы

Можно ли использовать pdf-lib как обычный PDF-редактор?

Нет. Это библиотека без окон, панелей и визуального выбора объектов. GUI должен реализовать ваш продукт или отдельный редактор.

Умеет ли pdf-lib распознавать сканы?

Нет встроенного OCR. Изображение можно встроить в PDF, но превращение скана в поисковый текст требует отдельного OCR-движка.

Можно ли извлечь весь текст PDF?

Высокоуровневый API читает значения form fields, но не обычный текст страницы. Для поиска и индексации нужен инструмент с text extraction, например PDF.js или Apache PDFBox.

Можно ли заменить слово в существующем абзаце?

Не как в Word. pdf-lib добавляет новый текст и меняет form fields, но не даёт API «найти строку и заменить её с перерасчётом верстки». Визуальное перекрытие старого текста не равно его удалению и не подходит для redaction.

Поддерживаются ли PDF с паролем?

Официально нет. ignoreEncryption не расшифровывает файл. Для password-protected PDF нужна библиотека с реальной поддержкой нужного шифрования.

Можно ли работать офлайн?

Да, если библиотека и ресурсы находятся внутри приложения. CDN нужен только если вы действительно загружаете оттуда JavaScript при запуске.

Почему русские буквы иногда вызывают ошибку?

Обычно используется стандартный WinAnsi-шрифт. Встройте подходящий шрифт через @pdf-lib/fontkit и применяйте его при рисовании и обновлении appearance.

Можно ли подписывать PDF электронной подписью?

В high-level API 1.17.1 нет полноценного процесса создания криптографической цифровой подписи. Signature field или картинка подписи не заменяют signing stack.

Сохранит ли pdf-lib действующую цифровую подпись существующего файла?

На это не следует рассчитывать. Версия 1.17.1 сохраняет документ полной сериализацией и не предоставляет high-level инкрементальное сохранение для сохранения подписанных byte ranges. Любое изменение подписанного PDF обычно требует отдельной стратегии цифровой подписи и проверки валидности после модификации.

Стоит ли начинать новый проект на pdf-lib в 2026 году?

Да, если нужен ограниченный набор проверенных операций и вы готовы зафиксировать 1.17.1, покрыть реальные PDF тестами и принять отсутствие свежих официальных релизов. Для шифрования, подписи, extraction или активной поддержки лучше заранее сравнить альтернативы.

Вывод

pdf-lib остаётся сильным инструментом там, где приложение на JavaScript должно создавать PDF, переставлять и копировать страницы, дорисовывать текст и графику, заполнять AcroForm, добавлять вложения и метаданные без обязательного облачного сервиса. MIT License, работа в Node и браузере и отсутствие отдельного нативного движка делают интеграцию сравнительно простой.

Главный аргумент против выбора в новом крупном проекте — не функциональность базовых API, а состояние поддержки: официальная версия 1.17.1 не обновлялась с ноября 2021 года. К этому добавляются принципиальные ограничения: нет OCR, обычного text extraction, полноценного редактирования существующего page-text и поддержки шифрованных PDF. Если эти функции входят в ядро продукта, лучше сразу выбрать более подходящую библиотеку или разделить pipeline между несколькими специализированными компонентами.

Sumatra PDF при таком выборе не является прямым конкурентом: это программа для чтения готового документа, а pdf-lib — программный конструктор и модификатор. В практической системе они могут находиться рядом: код формирует PDF через pdf-lib, автоматические проверки контролируют структуру, а пользователь открывает результат в независимом viewer. Такой подход особенно разумен для стабильных шаблонов и повторяемых операций, где версия зависимости зафиксирована и весь набор реальных входных документов покрыт тестами.