pdfrx-Initialization.md

pdfrx Initialization

If you use Flutter widgets like PdfViewer or PdfDocumentViewBuilder, they implicitly initialize the library by calling pdfrxFlutterInitialize.

But if you use PdfDocument directly, you should explicitly do either one of the following ways:

• Call pdfrxFlutterInitialize
• Call pdfrxInitialize
• Initialize things by yourself

The first one is the recommended and the easiest way to initialize Flutter app.

For pure Dart apps (or even some of Flutter apps), you can use pdfrxInitialize.

Initialize Things By Yourself

Basically, these initialization functions do the following things:

• Call WidgetsFlutterBinding.ensureInitialized (Flutter only)
• Set Pdfrx.cacheDirectoryPath
• Map PdfDocument factory/interop functions to actual platform ones
• Set Pdfrx.loadAsset (Flutter only)
• Configure the PDFium module path from PDFIUM_PATH when explicitly provided
• Call PdfrxEntryFunctions.init to initialize the PDFium library (internally calls FPDF_InitLibraryWithConfig)

Cache Directory

The mechanism to set Pdfrx.cacheDirectoryPath is different between pure Dart apps and Flutter apps:

Init. Func.	Underlying API	Notes
pdfrxInitialize	Directory.systemTemp	May not be suitable for mobile apps.
pdfrxFlutterInitialize	path_provider.getTemporaryDirectory	Always app local directory.

PdfFontManager uses ${Pdfrx.cacheDirectoryPath}/pdfrx.fonts as its default font cache directory. If you use PdfDocument directly and want cached fonts to be available during the first document load, initialize pdfrx or set Pdfrx.cacheDirectoryPath before creating/preparing the font manager.

PDFium Native Library

For pure Dart apps, PDFium is provided as a Dart native asset. The native library is downloaded and bundled at build time by the package build hook. This includes macOS CLI commands such as dart test, dart run, and dart compile, which use the native asset libpdfium.dylib.

For Flutter apps, pdfium_flutter is the recommended PDFium integration package for every native platform except Web. It uses native asset packaging on Android, Windows, and Linux, and the PDFium XCFramework on iOS and macOS. pdfium_dart detects Flutter on iOS/macOS and resolves PDFium from the linked XCFramework rather than loading the macOS native asset.

• PDFium binaries are downloaded from https://github.com/bblanchon/pdfium-binaries/releases during build
• Linux Flutter builds resolve libpdfium.so from the app's shared library directory relative to the executable
• You can explicitly specify a libpdfium shared library path by setting the PDFIUM_PATH environment variable
• Web builds use PDFium WASM instead of FFI