---
title: "Add PDF functionality with Next.js"
canonical_url: "https://www.nutrient.io/sdk/web/getting-started/nextjs/"
md_url: "https://www.nutrient.io/sdk/web/getting-started/nextjs.md"
last_updated: "2026-05-15T09:08:03.788Z"
description: "Learn how to integrate Nutrient Web SDK into your Next.js application. Complete guide with troubleshooting for App Router, TypeScript support, and common integration issues."
---
# Add PDF functionality with Next.js
Nutrient Web SDK is a JavaScript PDF library for viewing, annotating, and editing PDFs directly in the browser. Use it to add PDF capabilities to any web app.
This guide walks you through the steps to integrate Nutrient Web SDK into your project. By the end, you’ll be able to render a PDF document in the user interface (UI).
**Test without installing**
You can test the SDK capabilities in our playground.
[Read more](https://nutrient.io/demo/sandbox)
**Jump to example**
Prefer to jump straight to code? View the example repo on GitHub.
[Read more](https://github.com/PSPDFKit/nutrient-examples/tree/main/examples/nextjs)
## Installation
You can load Nutrient Web SDK directly from Nutrient’s content delivery network (CDN). Nutrient maintains the CDN for customers, and it’s our recommended way to get started. For more control and flexibility, use the local installation option.
#### Note: Creating a new project (optional)
If you don’t yet have a Next.js project set up, create one with:
```sh
npx create-next-app@latest nutrient-nextjs-example
```
### CDN installation
**Steps:**
1. Add the following in your Next.js layout component (for example, `layout.tsx`):
```tsx
// layout.tsx
import Script from "next/script";
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
{children}
);
}
```
2. You’re now ready to use Nutrient Web SDK and reference `window.NutrientViewer` in the client-side code.
### Install via package manager
**Steps:**
1. Add the Nutrient Web SDK (`@nutrient-sdk/viewer`) dependency:
```bash
npm install @nutrient-sdk/viewer
# or
yarn add @nutrient-sdk/viewer
# or
pnpm install @nutrient-sdk/viewer
```
2. If you tried CDN installation first, make sure to remove the script component:
```tsx
// layout.tsx
```
3. You’re now ready to use Nutrient Web SDK locally in your Next.js app.
## Rendering a PDF
This guide covers integration using [App Router](https://nextjs.org/docs/app) (Next.js 13+). You can use a similar approach for [Pages Router](https://nextjs.org/docs/pages) (Next.js 12 and earlier).
### CDN installation
**Steps:**
1. Load the PDF file into a component — for example, `page.tsx` — using `NutrientViewer`:
```tsx
// page.tsx
// Only render the SDK on the client side.
"use client";
import React, { useEffect, useRef } from "react";
export default function Home() {
const containerRef = useRef(null);
useEffect(() => {
const container = containerRef.current;
if (container && window.NutrientViewer) {
window.NutrientViewer.load({
container,
document: "https://www.nutrient.io/downloads/nutrient-web-demo.pdf",
});
}
return () => {
if (window.NutrientViewer && container) {
window.NutrientViewer.unload(container);
}
};
}, []);
// You must set the container height and width.
return (
);
}
```
2. Start the development server:
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```
3. You’ll see the PDF rendered in the Nutrient Web SDK user interface (UI).
### Install via package manager
**Steps:**
1. With package manager installation, access the Nutrient Web SDK module directly. Update your `page.tsx` file to load the PDF file as shown below:
```tsx
// page.tsx
// Only render the SDK on the client side.
"use client";
import React, { useEffect, useRef } from "react";
export default function Home() {
const containerRef = useRef(null);
useEffect(() => {
const container = containerRef.current;
let cleanup = () => {};
(async () => {
const NutrientViewer = (await import("@nutrient-sdk/viewer")).default;
// Ensure there's only one `NutrientViewer` instance.
NutrientViewer.unload(container);
if (container && NutrientViewer) {
NutrientViewer.load({
container,
useCDN: true,
document:
"https://www.nutrient.io/downloads/nutrient-web-demo.pdf",
});
}
cleanup = () => {
NutrientViewer.unload(container);
};
})();
return cleanup;
}, []);
// You must set the container height and width.
return (
);
}
```
> **Note:** Adding `useCDN: true` will load the SDK assets from the CDN if `baseUrl` isn’t provided. This flag was introduced in version 1.9.0. If your setup relies on the previous behavior of autodetecting the assets without `baseUrl`, you can omit this flag for now, but be aware that this behavior is deprecated. In future versions, loading from CDN will become a default when `baseUrl` isn’t explicitly provided. `useCDN: true` has no effect if `baseUrl` is set.
**Optional**: If you decide to self-host the Nutrient Web SDK assets, as [described in this guide](https://www.nutrient.io/guides/web/self-host-assets.md), make sure to provide a `baseUrl` in your configuration, as shown below:
```tsx
NutrientViewer.load({
container,
useCDN: true,
document: "https://www.nutrient.io/downloads/nutrient-web-demo.pdf",
baseUrl: `${window.location.protocol}//${window.location.host}/${
process.env.PUBLIC_URL?? "" // Usually empty for Next.js, but supports custom deployments.
}`,
});
```
2. Start the development server:
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```
## Next steps
This section outlines additional steps for setting up your project.
### TypeScript with CDN installation
Nutrient Web SDK comes with built-in support for TypeScript. This should work out of the box for the package manager installation. For the CDN installation, follow the steps below.
**Steps:**
1. Add the Nutrient Web SDK dependency, if not done previously. You need the package installed locally to reference the types:
```bash
npm install @nutrient-sdk/viewer
# or
yarn add @nutrient-sdk/viewer
# or
pnpm install @nutrient-sdk/viewer
```
2. Create a module for custom typings — for example, `global.d.ts` in the root directory — to reference the built-in typings for the SDK:
```ts
// global.d.ts
import NutrientViewer from "@nutrient-sdk/viewer";
declare global {
interface Window {
// Nutrient Web SDK will be available on `window.NutrientViewer` once loaded.
NutrientViewer?: typeof NutrientViewer;
}
}
export {}; // Make this file a module.
```
3. Restart the TypeScript server or your editor, if needed.
### Optimizing the CDN installation
If you use the CDN installation approach in production, we recommend considering optimizations such as [prefetching](https://developer.mozilla.org/en-US/docs/Glossary/Prefetch).
### Optimizing load performance
If your app doesn't open a PDF immediately — for example, the user navigates to a viewer on a different page — call [`NutrientViewer.preloadWorker()`](https://www.nutrient.io/api/web/functions/NutrientViewer.preloadWorker.html) early in your app to fetch and compile the WebAssembly artifacts in the background. When `NutrientViewer.load()` runs later, it can start rendering without waiting for them.
```js
// Call early — for example, on app init or after login.
NutrientViewer.preloadWorker();
```
Refer to the [performance best practices](https://www.nutrient.io/guides/web/best-practices/performance.md) guide for more optimization techniques.
## Known compatibility issues
**Next.js 16 Turbopack plus Nutrient Web SDK 1.14 and earlier:** In Next.js 16 production builds that use Turbopack, `next build` reminifies the Nutrient UMD bundle and can emit syntactically invalid JavaScript — specifically `new Foo?.()`, which V8 rejects at parse time with `Uncaught SyntaxError: Invalid optional chain from new expression`. The parse error fires before `await import("@nutrient-sdk/viewer")` settles, so the promise never resolves or rejects, and no error bubbles to your `try/catch`. The viewer silently fails to render. The issue affects `next build` production output only; `next dev` works. **Upgrade to the latest Nutrient Web SDK** to resolve this. If you cannot upgrade, use one of these workarounds:
- Run `next build --webpack` to opt out of Turbopack for production builds.
- Use the **CDN installation** approach shown above, or self-host `nutrient-viewer.js` and load it via a `