; } ``` ### Vue 3 ```vue ``` ### Angular ```typescript import { Component, ElementRef, ViewChild, AfterViewInit, OnDestroy, Input, } from "@angular/core"; @Component({ selector: "pdf-viewer", template: '

', }) export class PdfViewerComponent implements AfterViewInit, OnDestroy { @ViewChild("container") container!: ElementRef; @Input() documentId!: string; @Input() jwt!: string; @Input() serverUrl!: string; private instance: any; async ngAfterViewInit() { const NutrientViewer = (await import("@nutrient-sdk/viewer")).default; // Note: `ViewChild` is only available after view initialization. this.instance = await NutrientViewer.load({ container: this.container.nativeElement, documentId: this.documentId, authPayload: { jwt: this.jwt }, serverUrl: this.serverUrl, }); } ngOnDestroy() { this.instance?.unload(); } } ``` **Container timing:** In frameworks like Angular, the container element may not be available immediately. Ensure you wait for the view to initialize (e.g. use `ngAfterViewInit` in Angular or `useEffect`/`onMounted` in React/Vue) before calling `NutrientViewer.load()`. ## Cross-origin configuration (CORS) When your web application runs on a different domain than Document Engine, CORS must be configured via the JWT `allowed_origins` claim. ### Configuring allowed origins Document Engine uses the `allowed_origins` claim in the JWT to determine which origins are permitted. When [generating a JWT](https://www.nutrient.io/guides/document-engine/viewer/client-authentication/generate-a-jwt.md), include the `allowed_origins` claim with your frontend domain(s): ```json { "document_id": "abc123", "permissions": ["read-document"], "allowed_origins": ["https://your-app.com", "https://staging.your-app.com"] } ``` Set `allowed_origins` to `"any"` to allow requests from any origin (not recommended for production). ### Common CORS errors If you see an error like: > Access to fetch at `https://document-engine.example.com/i/d/5/auth` from origin `https://your-app.com` has been blocked by CORS policy Check that: 1. The JWT includes an `allowed_origins` claim with your frontend domain. 2. The protocol matches exactly (`http` vs `https`). 3. The port is included if using a non-standard port. Refer to the [JWT authentication](https://www.nutrient.io/guides/document-engine/viewer/client-authentication/generate-a-jwt.md) guide for details on configuring the `allowed_origins` claim. ## License and domain configuration Document Engine validates that requests originate from licensed domains. ### Origin validation errors If you see an error like: > PSPDFKit Document Engine is not licensed for use from the origin `http://localhost:8080` This means the requesting origin isn’t included in your license configuration. **To resolve:** - **Development** — Use a development license that includes `localhost`. - **Production** — [Contact Support](https://support.nutrient.io/hc/en-us/requests/new) to add your production domains to your license. Refer to the [domain configuration](https://www.nutrient.io/guides/document-engine/troubleshooting/license/domain-use-in-de.md) guide for more details. ## Differences from standalone mode When using Document Engine instead of standalone Web SDK, some behaviors differ. These are outlined in the table below. | Feature | Standalone | Document Engine | | ----------------------- | --------------------------- | --------------------------------------- | | Document source | URL, `ArrayBuffer`, or file | `documentId` on server | | Annotation storage | Local or custom backend | Server-managed | | `instantJSON` parameter | Loads annotations from JSON | Ignored — annotations managed by server | | `autoSaveMode` | Controls local saving | Controls syncing to Document Engine | | Document streaming | Not available | [Enabled by default](https://www.nutrient.io/guides/document-engine/viewer/streaming.md) | ## Performance considerations To improve load times within your application, we recommend using `preload` and `prefetch` in adequate scenarios: preloading `nutrient-viewer.js` for sites on which you wish to display PDF content using Nutrient, and prefetching on sites on which no PDF content is visible. The `preload` attribute of the `` tag causes your browser to start downloading the resource of the `` tag earlier in the lifecycle of your page, which will improve the overall feel of your site, while the `prefetch` attribute is used to fetch the resources you predict a user is likely to request. See the [HTML specification](https://www.w3.org/TR/resource-hints/) for more information. The implementation of these will depend on how you’re importing `nutrient-viewer.js` on your site/application. If your service is a regular website using vanilla JavaScript, you can add `` or `` within the `` of the pages in question. For websites and applications with modern frameworks that use webpack for bundling, this can be done using the `/* webpackPrefetch: true */` or `/* webpackPreload: true */` comments within your `import()`. Webpack will use this information to generate the appropriate `` or `` tags for you. See the [webpack documentation](https://webpack.js.org/guides/code-splitting/#prefetchingpreloading-modules) for more information. ## Version compatibility For best results, use compatible versions of Document Engine and Web SDK: - When serving Web SDK from Document Engine, versions are automatically matched. - When serving from CDN or bundling manually, ensure your Web SDK version is compatible with your Document Engine version. - Check the [requirements guide](https://www.nutrient.io/guides/document-engine/about/requirements.md) for minimum version compatibility. ## Troubleshooting This section covers common issues you may encounter when integrating Nutrient Web SDK with Document Engine, along with their solutions. For issues not listed here, refer to the related guides below or [contact Support](https://support.nutrient.io/hc/en-us/requests/new). ### Common errors | Error | Cause | Solution | | ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `container must be a valid element` | Element doesn’t exist when `load()` is called | Wait for DOM to be ready; use framework lifecycle hooks | | `Not licensed for origin` | Domain not in license | Add domain to license; see [domain configuration](https://www.nutrient.io/guides/document-engine/troubleshooting/license/domain-use-in-de.md) | | CORS errors | Cross-origin not configured | Add the `allowed_origins` claim to JWT | | Connection timeout | Network or timeout configuration | See the [504 response](https://www.nutrient.io/guides/document-engine/troubleshooting/errors-and-warnings/504-response.md) guide | | Authentication failed | Invalid or expired JWT | Regenerate JWT and verify claims (including `exp`). For expired tokens in long-running sessions, use runtime refresh with `onAuthFailed` + `setSession` | To renew JWTs without recreating the viewer, refer to the [web client authentication and session renewal](https://www.nutrient.io/guides/web/viewer/client-authentication.md) guide. ### Related guides - [Troubleshooting overview](https://www.nutrient.io/guides/document-engine/troubleshoot.md) - [HTTPS setup](https://www.nutrient.io/guides/document-engine/troubleshooting/getting-started/https.md) - [Document streaming](https://www.nutrient.io/guides/document-engine/viewer/streaming.md) - [License troubleshooting](https://www.nutrient.io/guides/document-engine/troubleshooting/license/license-troubleshooting.md)