Roadmap

[coolsoftwaretyler]

I'm building this Expo module because I needed a PDF view for an Expo project, and react-native-pdf hasn't had a release in a long while. I have a lot of respect for existing work done by OSS maintainers. Writing and maintaining OSS is a tiresome and thankless job, I do it quite a bit myself. There's nothing wrong with moving slowly on a project you do for free, but I've got enough energy and need that I figured I would build something new that works better for me. Maybe it'll work for others as well.

At the moment, I've been leaning heavily on Claude Code to help me with the implementation. The codebase includes an example Expo app with scenarios that test out the functionality side-by-side.

As with any open source, I'm doing this for free and for fun, so I may change the plan on a whim. But for now, here's a loose plan that potential contributors and consumers can expect:

v0.1.x Initial development (unstable, heavily AI generated)

In the initial development phase (current phase), I'm mostly working to get parity with the props API surface so that people can migrate between react-native-pdf to Cool PDF with minimal changes.

Since this phase uses a lot of AI generated code, you should probably read through the source before using it in production. I am reviewing as I go, but I plan to take a more detailed look during a later phase.

Event interface differences

Since this is an Expo module, some things won't translate precisely. Notably, event handlers have a slightly different type signature. I plan to leave this inconsistency for now, because I think the refactor for consumers is small, and I'd rather keep it looking like a conventional Expo module.

As an example:

// With Cool PDF:

        onLoadComplete={(event) => {
          const { numberOfPages, path, dimensions, tableContents } =
            event.nativeEvent;
            console.log(numberOfPages)
        }}

// With React Native PDF

        onLoadComplete={(numberOfPages, path, dimensions, tableContents) => {
          console.log(numberOfPages)
        }}

The events just have nativeEvent on them, but the nativeEvent object will satisfy the interface of the old API.

No support for out-of-tree-platforms

I'm not planning to implement support for out-of-tree platforms during this first phase. I know there are some React Native windows functionality built in to react-native-pdf, but I don't have a good plan to tackle things like that. Happy to accept PRs for this functionality, but I'm unlikely to test them thoroughly, so any support will be best-effort.

Fixing bugs and cross platform issues

In some cases, Expo modules make it easy to actually improve cross platform support. You may find that some props react-native-pdf lists as unsupported for platforms work on more platforms with Cool PDF. I'll enumerate these once I start documenting better. I have also found some bugs with the existing implementation that Cool PDF fix.

Dimension differences

I've noticed that some of the sizing metadata is different between React Native PDF and Cool PDF. I suspect this is from different underlying libraries. I intend to fix this eventually, but not during the first phase.

v0.2.x Testing, AI Cleanup, and Documentation

Once we support most of the props API surface of react native PDF, I'll start cleaning up the AI generated code. I'll do this in two phases:

1. First, I'll be writing automated tests with Maestro, Jest, and native platform tests to exercise as much of the existing functionality as possible, so that I can refactor the code confidently without manually testing every supported API.
2. Once I have a comprehensive test suite, I'll begin reading through the AI generated code and actually cleaning it up to be up to good engineering standards.
3. As I go through that process, I'll write real documentation about how things work, and any intentional differences between react-native-pdf and Cool PDF

v0.3.x in-the-weeds fixes

I expect this phase of the project to have the long-tail of in-the-weeds fixes, like fixing deviations between Cool PDF and react-native-pdf when it comes to measured dimensions and other details under-the-hood. It will be easier to fix these bugs once I have comprehensive tests and docs.

v1.x.z

I'll mark Cool PDF as stable once all the prior phases are complete, and I'll start following semantic versioning for breaking.feature.patch releases.

v2.x.z

Expo lists some alternatives to using PDF views, and I think most people should actually consider those. But I understand many projects require direct PDF views (I personally have a project that does). My long term goal is to provide a PDF component that has three modalities that can be controlled from a single JavaScript layer. I'll explore an API that allows users to keep using the react-native-pdf API, and choose to render it as a native view, inside a web browser, inside a webview, or via the share API.

Contributing

I'd welcome contributions, although I may hold off on certain changes depending on the phase of the project. For example, I'd love to have a PR that fixes the discrepancy between dimensions, but I'm unlikely to merge that until we've finished implementing the full API surface.

If you want to contribute code, please open an issue or comment on an existing issue so I know you're working on it.

If you want to help out without writing code, we could use as many QA testers as possible. Find some bugs and put together good reproductions for us to fix.