Self-host assets in Web SDK

When installing Nutrient Web SDK using a package manager, the SDK loads additional resources at runtime — for example, web workers, fonts, and icons — that must be served from a web server. As of version 1.9.0, you have an option to either load those assets automatically from CDN by setting useCDN: true, which should be enough for most use cases. However, if you need complete control over the dependencies for compliance, offline functionality, security policies, or performance optimization, you can serve the SDK assets yourself.

Prerequisites

This guide assumes you’ve already installed Nutrient Web SDK via a package manager. The assets archive below contains only the runtime dependencies (WebAssembly binaries, fonts, and icons) that the SDK loads at runtime — it’s not a standalone SDK distribution. Refer to the getting started guide for installation instructions.

Self-hosting assets

Follow the steps below to self-host the SDK assets.

  1. Download the assets archive(opens in a new tab).

  2. Extract the contents of the archive directly into your application’s public directory — for example, /public/. The extracted files should be accessible at your application’s root URL when served.

  3. Configure the SDK to load the assets from your server by setting the baseUrl option when initializing the SDK:

    NutrientViewer.load({
      container,
      document: "/nutrient-web-demo.pdf", // Place your PDF in the public directory.
      baseUrl: `${window.location.protocol}//${window.location.host}/${
        import.meta.env.PUBLIC_URL ?? "" // Usually empty for Vite, but supports custom deployments.
      }`,
    });

  4. Verify self-hosting is working:

    • Start your development server.
    • Open browser DevTools and navigate to the Network tab.
    • Load a PDF in your application.
    • Confirm SDK assets are being loaded from your domain, and not from cdn.cloud.pspdfkit.com.

Why this change?

Starting with version 1.9.0, we changed how runtime assets are distributed. This shift addresses real challenges developers encountered with modern build tools and deployment workflows while making the SDK more flexible for different use cases.

Cleaner assets for self-hosting

Build tools like Vite and Webpack often struggled to locate large binary files buried deep within node_modules hierarchies. The self-host ZIP provides a stable, predictable source for these assets that doesn’t depend on npm’s folder structure or build tool resolution quirks. You get a clean reference point that works consistently across different environments.

Smaller package size

Separating large binary assets from the core package keeps installations lean and efficient. This means faster npm installs, quicker CI/CD pipelines, and less bandwidth consumption, which is especially valuable for teams working with constrained network conditions or deploying frequently. Your project only downloads what it actively needs.

Easier for most, flexible for you

The SDK now defaults to CDN mode for the simplest possible setup experience. Most teams can get started immediately without worrying about asset management. But if you need strict control — whether for compliance requirements, air-gapped environments, offline functionality, or security policies — the self-hosting path remains fully supported and straightforward.

Looking ahead

We’ve kept the old approach working during this transition period, giving everyone time to migrate comfortably. The deprecation warning gently nudges you toward the new method before we eventually phase out the old files. We’re also actively exploring package manager integration to make self-hosting even smoother down the road, based on feedback from teams that need that level of control.

Deprecation warning: Prior to version 1.9.0, the recommended way to self-host assets was by using the files inside node_modules/@nutrient-sdk/viewer/dist/nutrient-viewer-lib. This is no longer recommended and will result in a warning in the console. Use the method described above instead. This change improves the SDK installation experience by providing more flexibility in how you manage and deploy assets.