PDFJS is too hard to use (constructive criticism)

[burtonator]

PDFJS is very difficult to use as an API and I thought I would write up the problems I have so that it can be fixed. Please view all the above as constructive. We're using PDFJS extensively in Polar (getpolarized.io) and want to continue doing so but our productivity using the API is very low.

Here are my suggestions:

• Improve API and usage documentation. Only simple usage of PDF.js is documented. Other than that you have to dive into the code to figure things out. An example is the PDFFindController. There's no documentation for it and you have to figure things out yourself by reading the source code.

• Typescript bindings are non-existent and/or don't work. This is a HUGE opportunity to fix the documentation problem. The current bindings have idiosyncrasies and inconsistent documentation vs the main source code. The types aren't updated often either. I think this should be a priority because a lot of NEW developers are using Typescript and this would dramatically simplify usage of pdfs.js

• More complete examples. The examples used currently are basic and don't go into advanced usage of the API. For example, I have no idea how to get the outline for the sidebar as it's not documented anywhere other than the source code.

• How does the 'windowed' scrolling work in the viewer? It looks like there's a queue of pages that can be loaded but in my viewer ALL the documents are loaded. I don't think there's any documentation on this so I can't figure it out.

... I think if there was a simpler documentation of the API then we could at least compile the typescript buildings automatically. I know work is being done on this now but it's been a long time to get it out the door. I think even hand written bindings could be better than no bindings.

Maybe the 2.4 release is an opportunity to fix these issues?

[Snuffleupagus]

Please keep in mind that this is an open-source project, with most of the development now being done by unpaid volunteers.

Note also that the main reason for this project existing is to provide the Firefox PDF Viewer, and keeping that working is probably what most of the contributors are primarily concerned with.

---

Improve API and usage documentation.

Writing good documentation can be both difficult and time-consuming unfortunately...

An example is the PDFFindController. There's no documentation for it and you have to figure things out yourself by reading the source code.

Basic usage can be seen in the "viewer components" examples, see link further below.

Typescript bindings

That's already being tracked in issue #7909.
As has been mentioned elsewhere: the only realistic solution would be to generate the TypeScript definitions automatically, since it's not reasonable for the few remaining PDF.js contributors to have to maintain that manually (on top of everything else).

More complete examples.

Please see https://github.com/mozilla/pdf.js/tree/master/examples/components, which shows how to use the "viewer components" rather than the API directly.

How does the 'windowed' scrolling work in the viewer?

This may be because the current code expects the viewer element to be absolutely positioned; already tracked in issue #11626.

Maybe the 2.4 release is an opportunity to fix these issues?

Unless there's any significant regressions, that release is already done; note the current pre-release at https://github.com/mozilla/pdf.js/releases

[burtonator]

Thanks for the explanation. I'll try to keep documenting these issues.

I think my biggest recommendation is to not wait for typescript bindings to be perfect and just accept them now. Part of the problem is that they were decoupled I think. If they're integrated into pdfjs I can just send PRs easier.

Yeah. Would be nice if it was auto generated we can improve them over time this way.

[Snuffleupagus]

Given that the actionable points of #11759 (comment) are already tracked elsewhere, as mentioned in #11759 (comment), and that the remaining points are essentially covered by the third paragraph of https://github.com/mozilla/pdf.js/blob/master/.github/CONTRIBUTING.md I'd suggest simply closing this issue. /cc @timvandermeij

[timvandermeij]

Yes, I think this is also covered sufficiently in existing issues now.