π fix(pdf): ensure worker config before Document render#11746
Conversation
Fixes "No GlobalWorkerOptions.workerSrc specified" error in TurboPack by: - Creating unified pdfjs module that ensures worker config at render time - Wrapping Document component to call ensureWorker() before render - Removing side-effect imports that may be optimized away by bundler Closes LOBE-4108
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
Reviewer's GuideIntroduces a unified pdfjs wrapper module that ensures the PDF worker is configured before any render, updates call sites to use it, and removes fragile side-effect-based worker setup while making a minor cleanup in a PDF viewer map callback. Sequence diagram for ensuring pdfjs worker before Document rendersequenceDiagram
actor User
participant ReactComponent as PDFViewer_or_PdfPreview
participant WrapperDocument as Document
participant PdfJS as pdfjs
participant GlobalWorkerOptions
participant PdfDocument as ReactPdf_Document
User->>ReactComponent: Navigate to PDF view
ReactComponent->>WrapperDocument: Render Document(props)
WrapperDocument->>WrapperDocument: ensureWorker()
WrapperDocument->>PdfJS: Access pdfjs.GlobalWorkerOptions.workerSrc
alt workerSrc not set
WrapperDocument->>GlobalWorkerOptions: Set workerSrc = workerSrc_constant
end
WrapperDocument->>PdfDocument: Render PdfDocument(props)
PdfDocument-->>ReactComponent: Rendered PDF pages
ReactComponent-->>User: Display PDF without workerSrc error
Class diagram for unified pdfjs wrapper moduleclassDiagram
class pdfjs {
+string version
}
class GlobalWorkerOptions {
+string workerSrc
}
class PdfDocument {
<<external>>
}
class PdfPage {
<<external>>
}
class PdfjsModule {
+string workerSrc
+ensureWorker() void
}
class Document {
+props DocumentProps
+render() void
}
class Page {
<<re_export>>
}
class DocumentProps {
}
class PageProps {
}
PdfjsModule --> pdfjs : uses
PdfjsModule --> GlobalWorkerOptions : configures
Document --> PdfjsModule : calls ensureWorker
Document --> PdfDocument : wraps
Page --> PdfPage : re_exports
DocumentProps --> PdfDocument : based_on
PageProps --> PdfPage : based_on
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
TestGru AssignmentSummary
Tip You can |
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- Consider making
workerSrcconfigurable (e.g., via an env or a small config helper) instead of hardcoding the npm mirror URL so that deployments can switch CDNs or self-host the worker without touching code. - The new
ensureWorkerhelper only checkspdfjs.GlobalWorkerOptions.workerSrc; if other worker-related global options are required in the future (e.g., different worker for SSR vs client), it might be worth centralizing all worker configuration there to avoid scattered setups.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Consider making `workerSrc` configurable (e.g., via an env or a small config helper) instead of hardcoding the npm mirror URL so that deployments can switch CDNs or self-host the worker without touching code.
- The new `ensureWorker` helper only checks `pdfjs.GlobalWorkerOptions.workerSrc`; if other worker-related global options are required in the future (e.g., different worker for SSR vs client), it might be worth centralizing all worker configuration there to avoid scattered setups.
## Individual Comments
### Comment 1
<location> `src/libs/pdfjs/index.tsx:6` </location>
<code_context>
+import type { ComponentProps } from 'react';
+import { Document as PdfDocument, Page as PdfPage, pdfjs } from 'react-pdf';
+
+const workerSrc = `https://registry.npmmirror.com/pdfjs-dist/${pdfjs.version}/files/build/pdf.worker.min.mjs`;
+
+function ensureWorker() {
</code_context>
<issue_to_address>
**suggestion:** Consider making the worker URL configurable instead of hardcoding a specific CDN/mirror.
Using a hardcoded `registry.npmmirror.com` URL tightly couples the app to a single external mirror and can cause issues with regional access, outages, or CSP-restricted environments. Please source this URL from configuration (env, runtime config, or a shared constants module) with a reasonable default so deployments can select their own hosting (e.g., self-hosted asset or preferred CDN).
Suggested implementation:
```typescript
import type { ComponentProps } from 'react';
import { Document as PdfDocument, Page as PdfPage, pdfjs } from 'react-pdf';
const DEFAULT_PDF_WORKER_SRC = `https://registry.npmmirror.com/pdfjs-dist/${pdfjs.version}/files/build/pdf.worker.min.mjs`;
/**
* Resolve the PDF worker source URL from configuration with a sensible default.
*
* Prefer an environment-driven configuration so deployments can select their own
* hosting (self-hosted assets, preferred CDN, etc.).
*/
const pdfWorkerSrc =
// Public runtime config (e.g. Next.js) β adjust name to match your conventions if needed
process.env.NEXT_PUBLIC_PDFJS_WORKER_URL ??
DEFAULT_PDF_WORKER_SRC;
function ensureWorker() {
if (!pdfjs.GlobalWorkerOptions.workerSrc) {
pdfjs.GlobalWorkerOptions.workerSrc = pdfWorkerSrc;
}
}
```
1. Define the environment variable (e.g. `NEXT_PUBLIC_PDFJS_WORKER_URL`) in your runtime configuration (.env or equivalent) if you want to override the default worker URL in specific environments.
2. If your project uses a different pattern for exposing public runtime config (for example, a `config` module or `publicRuntimeConfig` via Next.js), you may want to replace the `process.env.NEXT_PUBLIC_PDFJS_WORKER_URL` access with that shared configuration source instead, while keeping the same fallback to `DEFAULT_PDF_WORKER_SRC`.
</issue_to_address>
### Comment 2
<location> `src/libs/pdfjs/index.tsx:17-25` </location>
<code_context>
+export type DocumentProps = ComponentProps<typeof PdfDocument>;
+export type PageProps = ComponentProps<typeof PdfPage>;
+
+export const Document = (props: DocumentProps) => {
+ ensureWorker();
+ return <PdfDocument {...props} />;
+};
+
+
+
+
+export {Page, pdfjs} from 'react-pdf';
\ No newline at end of file
</code_context>
<issue_to_address>
**issue (bug_risk):** Page is re-exported without ensureWorker, which can break future usages that donβt go through Document.
Because `Page` is re-exported directly from `react-pdf`, it assumes callers always render it under this wrapped `Document`. If someone later imports `{ Page }` from this module and uses it elsewhere, the worker may not be initialized and PDF rendering can fail. To avoid this, export a local `Page` wrapper that calls `ensureWorker()` before delegating to `PdfPage`.
</issue_to_address>Help me be more useful! Please click π or π on each comment and I'll use the feedback to improve your reviews.
| import type { ComponentProps } from 'react'; | ||
| import { Document as PdfDocument, Page as PdfPage, pdfjs } from 'react-pdf'; | ||
|
|
||
| const workerSrc = `https://registry.npmmirror.com/pdfjs-dist/${pdfjs.version}/files/build/pdf.worker.min.mjs`; |
There was a problem hiding this comment.
suggestion: Consider making the worker URL configurable instead of hardcoding a specific CDN/mirror.
Using a hardcoded registry.npmmirror.com URL tightly couples the app to a single external mirror and can cause issues with regional access, outages, or CSP-restricted environments. Please source this URL from configuration (env, runtime config, or a shared constants module) with a reasonable default so deployments can select their own hosting (e.g., self-hosted asset or preferred CDN).
Suggested implementation:
import type { ComponentProps } from 'react';
import { Document as PdfDocument, Page as PdfPage, pdfjs } from 'react-pdf';
const DEFAULT_PDF_WORKER_SRC = `https://registry.npmmirror.com/pdfjs-dist/${pdfjs.version}/files/build/pdf.worker.min.mjs`;
/**
* Resolve the PDF worker source URL from configuration with a sensible default.
*
* Prefer an environment-driven configuration so deployments can select their own
* hosting (self-hosted assets, preferred CDN, etc.).
*/
const pdfWorkerSrc =
// Public runtime config (e.g. Next.js) β adjust name to match your conventions if needed
process.env.NEXT_PUBLIC_PDFJS_WORKER_URL ??
DEFAULT_PDF_WORKER_SRC;
function ensureWorker() {
if (!pdfjs.GlobalWorkerOptions.workerSrc) {
pdfjs.GlobalWorkerOptions.workerSrc = pdfWorkerSrc;
}
}- Define the environment variable (e.g.
NEXT_PUBLIC_PDFJS_WORKER_URL) in your runtime configuration (.env or equivalent) if you want to override the default worker URL in specific environments. - If your project uses a different pattern for exposing public runtime config (for example, a
configmodule orpublicRuntimeConfigvia Next.js), you may want to replace theprocess.env.NEXT_PUBLIC_PDFJS_WORKER_URLaccess with that shared configuration source instead, while keeping the same fallback toDEFAULT_PDF_WORKER_SRC.
| export const Document = (props: DocumentProps) => { | ||
| ensureWorker(); | ||
| return <PdfDocument {...props} />; | ||
| }; | ||
|
|
||
|
|
||
|
|
||
|
|
||
| export {Page, pdfjs} from 'react-pdf'; No newline at end of file |
There was a problem hiding this comment.
issue (bug_risk): Page is re-exported without ensureWorker, which can break future usages that donβt go through Document.
Because Page is re-exported directly from react-pdf, it assumes callers always render it under this wrapped Document. If someone later imports { Page } from this module and uses it elsewhere, the worker may not be initialized and PDF rendering can fail. To avoid this, export a local Page wrapper that calls ensureWorker() before delegating to PdfPage.
Codecov Reportβ
All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## next #11746 +/- ##
==========================================
- Coverage 74.17% 74.17% -0.01%
==========================================
Files 1193 1193
Lines 94958 94958
Branches 12966 10491 -2475
==========================================
- Hits 70437 70434 -3
- Misses 24431 24434 +3
Partials 90 90
Flags with carried forward coverage won't be shown. Click here to find out more.
π New features to boost your workflow:
|
|
β€οΈ Great PR @Innei β€οΈ The growth of project is inseparable from user feedback and contribution, thanks for your contribution! If you are interesting with the lobehub developer community, please join our discord and then dm @arvinxx or @canisminor1990. They will invite you to our private developer channel. We are talking about the lobe-chat development or sharing ai newsletter around the world. |
## [Version 2.0.0-next.354](v2.0.0-next.353...v2.0.0-next.354) <sup>Released on **2026-01-23**</sup> #### β» Code Refactoring - **misc**: Migrate AI Rules to Claude Code Skills. #### π Bug Fixes - **pdf**: Ensure worker config before Document render. <br/> <details> <summary><kbd>Improvements and Fixes</kbd></summary> #### Code refactoring * **misc**: Migrate AI Rules to Claude Code Skills, closes [#11737](#11737) ([346fc46](346fc46)) #### What's fixed * **pdf**: Ensure worker config before Document render, closes [#11746](#11746) ([ad34072](ad34072)) </details> <div align="right"> [](#readme-top) </div>
|
π This PR is included in version 2.0.0-next.354 π The release is available on: Your semantic-release bot π¦π |
## [Version 1.154.0](v1.153.1...v1.154.0) <sup>Released on **2026-01-23**</sup> #### β» Code Refactoring - **misc**: Migrate AI Rules to Claude Code Skills. #### β¨ Features - **database**: Extended async task with metadata and parent id, added index. - **misc**: Remove NextAuth. #### π Bug Fixes - **copilot**: History popover not refreshing when agentId changes. - **editor**: Prevent crash when toggling enableInputMarkdown setting. - **home**: Use correct CreateGroupModal for session group creation. - **model-runtime**: Handle null content in anthropic message builder. - **ModelSelect**: Resolve tooltip hover causing popup to close. - **pdf**: Ensure worker config before Document render. - **store**: Delete message before regeneration. - **misc**: Fix auto scroll, fix favorite refresh bug and group topic refresh issue, fixed the agent group builder tools excaution edge case crash, page content switch mismatch, when use market group, the group sys role was not used. <br/> <details> <summary><kbd>Improvements and Fixes</kbd></summary> #### Code refactoring * **misc**: Migrate AI Rules to Claude Code Skills, closes [lobehub#11737](https://github.com/jaworldwideorg/OneJA-Bot/issues/11737) ([346fc46](346fc46)) #### What's improved * **database**: Extended async task with metadata and parent id, added index, closes [lobehub#11712](https://github.com/jaworldwideorg/OneJA-Bot/issues/11712) ([31d2f26](31d2f26)) * **misc**: Remove NextAuth, closes [lobehub#11732](https://github.com/jaworldwideorg/OneJA-Bot/issues/11732) ([1eff864](1eff864)) #### What's fixed * **copilot**: History popover not refreshing when agentId changes, closes [lobehub#11731](https://github.com/jaworldwideorg/OneJA-Bot/issues/11731) ([64f39e7](64f39e7)) * **editor**: Prevent crash when toggling enableInputMarkdown setting, closes [lobehub#11755](https://github.com/jaworldwideorg/OneJA-Bot/issues/11755) ([ea5eed8](ea5eed8)) * **home**: Use correct CreateGroupModal for session group creation, closes [lobehub#11752](https://github.com/jaworldwideorg/OneJA-Bot/issues/11752) ([36bcc50](36bcc50)) * **model-runtime**: Handle null content in anthropic message builder, closes [lobehub#11756](https://github.com/jaworldwideorg/OneJA-Bot/issues/11756) ([539753a](539753a)) * **ModelSelect**: Resolve tooltip hover causing popup to close, closes [lobehub#11742](https://github.com/jaworldwideorg/OneJA-Bot/issues/11742) ([1b73f14](1b73f14)) * **pdf**: Ensure worker config before Document render, closes [lobehub#11746](https://github.com/jaworldwideorg/OneJA-Bot/issues/11746) ([ad34072](ad34072)) * **store**: Delete message before regeneration, closes [lobehub#11760](https://github.com/jaworldwideorg/OneJA-Bot/issues/11760) ([a8a6300](a8a6300)) * **misc**: Fix auto scroll, closes [lobehub#11734](https://github.com/jaworldwideorg/OneJA-Bot/issues/11734) ([892fa9f](892fa9f)) * **misc**: Fix favorite refresh bug and group topic refresh issue, closes [lobehub#11745](https://github.com/jaworldwideorg/OneJA-Bot/issues/11745) ([5d115ef](5d115ef)) * **misc**: Fixed the agent group builder tools excaution edge case crash, closes [lobehub#11735](https://github.com/jaworldwideorg/OneJA-Bot/issues/11735) ([5de4742](5de4742)) * **misc**: Page content switch mismatch, closes [lobehub#11758](https://github.com/jaworldwideorg/OneJA-Bot/issues/11758) ([fdc8f95](fdc8f95)) * **misc**: When use market group, the group sys role was not used, closes [lobehub#11739](https://github.com/jaworldwideorg/OneJA-Bot/issues/11739) ([afc76f9](afc76f9)) </details> <div align="right"> [](#readme-top) </div>
π» Change Type
π Related Issue
Closes LOBE-4108
π Description of Change
Fixes "No GlobalWorkerOptions.workerSrc specified" error that occurs with TurboPack bundler.
Root Cause:
import '@/libs/pdfjs/worker') may be optimized away by TurboPack'use client'componentsSolution:
@/libs/pdfjsmodule that wraps theDocumentcomponentensureWorker()before render, guaranteeing worker config is setChanges:
src/libs/pdfjs/index.tsx- New unified module with wrapped Document componentsrc/features/FileViewer/Renderer/PDF/index.tsx- Import from unified modulesrc/features/ShareModal/SharePdf/PdfPreview.tsx- Import from unified modulesrc/libs/pdfjs/worker.tsandsrc/libs/pdfjs/pdf.worker.tsπ§ͺ How to Test
Summary by Sourcery
Ensure PDF.js worker is configured before rendering PDF documents to avoid runtime errors with TurboPack bundling.
Bug Fixes:
Enhancements: