Livewire Pdf Preview Laravel Package

Getting Started

This package wraps Mozilla's pdf.js for use inside Laravel apps, so you can render PDFs client-side without shipping documents through a third-party viewer. The 1.0.2 release is a maintenance + flexibility bump: it refreshes the bundled pdf.js/pdf.worker.js to the latest upstream version, exposes a configurable worker path, and renames the install command.

Minimal setup:

1. Install the package via Composer.
2. Run the install command (note the 1.0.2 rename — check php artisan list for the current command name rather than copying old docs/tutorials).
3. Publish the package assets/config so the bundled pdf.worker.js is available under public/ or your asset pipeline.
4. Wire the viewer into a Blade view: point it at your PDF route and let pdf.js handle rendering.

First use case to validate end-to-end: a single <iframe>/<canvas> viewer loading a PDF from Storage::url(...) behind your normal auth middleware. If that renders, the worker is being found and served correctly — which is the single most common failure point with this package.

Where to look first:

• The package's published config file — look for the worker path key introduced in 1.0.2.
• The bundled pdf.worker.js location in public/vendor/... after publishing.
• The Blade/JS view stub the package ships, if any.

Implementation Patterns

Standard config-based worker path. With 1.0.2 you can point the viewer at a custom worker URL instead of relying on the package's default. This is the pattern to adopt when:

• Your app serves assets from a CDN or a non-default public path.
• You run behind a reverse proxy/subdirectory and the default absolute path breaks.
• You pin a specific upstream pdf.js version and want the worker to match it.

Configure it once in config/...php (or env) and let the package's JS pick it up — avoid hardcoding worker URLs in Blade templates.

Auth-gated PDF streaming. Keep PDFs behind Laravel routes, not public storage. Pattern: define a route with auth/can middleware that streams via response()->file(...) or Storage::download(...), then have the viewer fetch that URL. Do not expose storage/app publicly just to satisfy the viewer.

Version pinning between API and worker. Because 1.0.2 bumps the bundled worker, treat pdf.js core and pdf.worker.js as a matched pair. If you override the worker path to a CDN copy, pin the CDN URL to the exact version the package ships — mismatched major API/worker versions produce cryptic rendering failures.

Blade integration. Wrap viewer initialization in a small dedicated JS module rather than inlining it per page; pass the PDF URL and worker path as data attributes or a config object. This keeps the upgrade path clean when the package updates pdf.js again.

Install command naming. If you have deploy scripts, Dockerfiles, or CI steps invoking the installer, audit them against 1.0.2's renamed command. This is the kind of change that silently fails deploys rather than failing tests.

Gotchas and Tips

• The renamed install command is the main upgrade hazard. Anything that shells out to the old command name (deploy scripts, provisioning docs, README snippets in your repo) will break. grep your codebase and CI config for the old invocation before upgrading.
• Worker 404s are the #1 symptom. If the PDF viewer loads a blank page or the console shows a failed fetch for pdf.worker.js, it's almost always a path issue, not a pdf.js bug. With 1.0.2, the new custom worker path parameter is the fix — check whether your asset pipeline (Vite, Mix, CDN) has moved the file away from the default location.
• Cache busting. After upgrading a bundled JS worker, browsers and CDNs may serve the old cached file. Version your asset URLs or clear the CDN cache post-deploy; a stale worker against a new pdf.js core is a nasty, hard-to-reproduce class of bug.
• Upstream bump = behavior changes. "Newest version" of pdf.js can include rendering differences, deprecated API removals, and changed default behaviors. Smoke-test any complex PDFs (forms, annotations, large documents) your app actually renders — don't assume a worker bump is cosmetic.
• Config caching. If you add the new worker path setting, remember php artisan config:cache will freeze it; changes to the config/env value won't take effect until re-cached. Common "my config change did nothing" trap.
• Extension point. The custom worker path is the intended customization seam — use it rather than editing published vendor assets directly, so future package updates don't clobber your changes.
• Asset publishing on upgrade. Re-publish the package assets after upgrading so the new pdf.worker.js actually lands in public/. A composer update alone won't move the file if it's been published previously.