The app loads, but previews fail in an older WebView
A focused compatibility investigation: separate syntax, runtime APIs and Worker loading, then verify the same production assets in the actual host.
- WebView
- Compatibility
- PDF.js
- Worker
Related case: Smart ledger and order management. The preview feature uses PDF.js, SheetJS and docx-preview. This article concerns dependency compatibility, not document parsing or pagination algorithms.
Loading the home page proves very little
Preview libraries are often loaded on demand. A dependency that never ran during startup can fail only when the user opens a document.
A desktop host’s WebView may also differ from the installed browser. Record the host, engine, platform, build mode and asset versions before comparing results.
Identify the failing layer
| Layer | Symptom | First evidence |
|---|---|---|
| Syntax | Module fails to parse | Exact resource and unsupported syntax |
| Runtime API | A method is missing | Engine support and polyfill scope |
| Worker startup | Library loads but parsing fails | Worker response, version and environment |
| Rendering | Page exists but drawing fails | Canvas dimensions and render inputs |
“Blank preview” describes the user experience, not the responsible layer.
Compilation targets are not a full compatibility strategy
Lowering a target can transform some syntax. It does not implement every missing DOM method or ensure that dependencies and Workers use the same transformation path.
A conservative probe can reveal missing capabilities:
var capabilities = {
promise: typeof Promise === 'function',
fetch: typeof fetch === 'function',
worker: typeof Worker === 'function',
abortController: typeof AbortController === 'function',
replaceChildren:
typeof Element !== 'undefined' &&
typeof Element.prototype.replaceChildren === 'function'
}
console.table(capabilities)Passing this probe does not prove full preview support. If a script fails during parsing, the probe inside that script will never run; inspect console errors and resource responses first.
Verify the Worker separately
Check whether the Worker URL returns JavaScript instead of an HTML route fallback, whether it matches the library version and whether its script can execute in the host.
The project imports a separate PDF Worker resource. Such file paths belong to a dependency version and need rechecking during upgrades.
PDF.js examples distinguish document loading, page access and rendering, and caution against concurrent rendering into one Canvas. Those stages provide useful diagnostic boundaries.
Make compatibility decisions reversible
Options include upgrading the host engine, choosing a maintained compatible build, supplying specific APIs or offering a download fallback. Compare the actual environments and maintenance cost.
When a historical fix pins an older dependency, document why, where it applies and what would allow an upgrade; assess maintenance and security status rather than treating one successful test as a permanent justification.
Test identical built assets
Start with a small known document. Compare the same production assets in a modern browser and the target host, checking entry loading, dependency loading, Worker startup and rendering separately.
Development servers can alter paths and loading behavior. Browser H5 checks do not replace testing inside the actual desktop or Mini Program WebView. The runtime environment belongs in the dependency contract.