---
title: "Add PDF functionality with TypeScript | Nutrient Web SDK"
canonical_url: "https://www.nutrient.io/sdk/web/getting-started/typescript/"
md_url: "https://www.nutrient.io/sdk/web/getting-started/typescript.md"
last_updated: "2026-06-08T22:00:44.456Z"
description: "Learn how to integrate Nutrient Web SDK into your TypeScript application. Step-by-step guide for adding PDF viewing, editing, and annotation features."
---
# Add PDF functionality with TypeScript
Nutrient Web SDK is a PDF library for viewing, annotating, and editing PDFs directly in the browser. Use it to add PDF capabilities to any web application.
This guide walks you through the necessary steps to integrate Nutrient Web SDK into your TypeScript 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/typescript-vite)
## Prerequisites
- The [latest stable version of Node.js](https://nodejs.org/en/download/package-manager).
- A package manager compatible with [npm](https://docs.npmjs.com/about-npm). This guide contains usage examples for [Yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), and the [npm client](https://docs.npmjs.com/cli/v7/commands/npm). The npm client is installed with Node.js by default.
> Node.js is required to complete this guide, but it’s not a general requirement for using Nutrient Web SDK.
## Adding Nutrient Web SDK
#### Note: Creating a new project (optional)
If you don’t yet have a TypeScript project set up, create one with Vite’s TypeScript template.
**Steps:**
1. Run the following command to create a new Vite project with TypeScript:
```bash
npm create vite nutrient-typescript-example --template vanilla-ts
# or
yarn create vite nutrient-typescript-example --template vanilla-ts
# or
pnpm create vite nutrient-typescript-example --template vanilla-ts
```
2. Navigate to the project directory:
```sh
cd nutrient-typescript-example
```
3. Install dependencies (skip this if they were already installed during project creation):
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.
### CDN installation
**Steps:**
1. Update your `index.html` file to add the CDN script tag:
```html
Nutrient Web SDK viewer — TypeScript example
```
2. Install the Nutrient Web SDK package to get TypeScript types:
```bash
npm install @nutrient-sdk/viewer
# or
yarn add @nutrient-sdk/viewer
# or
pnpm install @nutrient-sdk/viewer
```
> Even though you’re loading the SDK from the CDN, you need the package installed locally to access TypeScript type definitions. The package won’t be bundled into your client code; it’s only used by TypeScript’s compiler for type checking.
3. Create a type declaration file, `src/global.d.ts`, to make `window.NutrientViewer` available with the proper types:
```ts
// src/global.d.ts
import NutrientViewer from "@nutrient-sdk/viewer";
declare global {
interface Window {
// Nutrient Web SDK will be available on `window.NutrientViewer` once loaded from the CDN.
NutrientViewer?: typeof NutrientViewer;
}
}
```
4. Ensure `#app` has an explicit height and width set:
```css
#app {
height: 100dvh;
width: 100dvw;
}
```
> Nutrient Web SDK requires that the mounting container has an explicit width and height before calling `NutrientViewer.load()`.
5. Replace the contents of `src/main.ts` with code to create a container, and load a PDF using `window.NutrientViewer`:
```ts
import "./style.css";
function load() {
const { NutrientViewer } = window;
if (!NutrientViewer) {
throw new Error("NutrientViewer is not available on window");
}
const container = document.getElementById("app");
if (!container) {
throw new Error("Container element not found");
}
// Ensure there's only one `NutrientViewer` instance.
NutrientViewer.unload(container);
NutrientViewer.load({
container,
document: "https://www.nutrient.io/downloads/nutrient-web-demo.pdf",
}).then((instance) => {
console.log("Nutrient loaded", instance);
}).catch(console.error);
}
load();
```
6. Start the development server:
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```
7. Open your browser and navigate to the URL displayed in the terminal (typically [http://localhost:5173](http://localhost:5173)). You’ll see the PDF document rendered in the viewer.
### 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 CDN script tag:
```html
```
3. Ensure `#app` has an explicit height and width set:
```css
#app {
height: 100dvh;
width: 100dvw;
}
```
> Nutrient Web SDK requires that the mounting container has an explicit width and height before calling `NutrientViewer.load()`.
4. Replace the contents of `src/main.ts` with code to create a container and dynamically import `NutrientViewer`:
```ts
// main.ts
import "./style.css";
async function load() {
// Dynamically import `NutrientViewer`.
const module = await import("@nutrient-sdk/viewer");
const NutrientViewer = module.default;
const container = document.getElementById("app");
if (!container) {
throw new Error("Container element not found");
}
// Ensure there's only one `NutrientViewer` instance.
NutrientViewer.unload(container);
NutrientViewer.load({
container,
document: "https://www.nutrient.io/downloads/nutrient-web-demo.pdf",
useCDN: true,
}).then((instance) => {
console.log("Nutrient loaded", instance);
}).catch(console.error);
}
load();
```
> **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:
```ts
NutrientViewer.load({
container,
useCDN: true,
document: "https://www.nutrient.io/downloads/nutrient-web-demo.pdf",
baseUrl: `${window.location.protocol}//${window.location.host}/${
import.meta.env.PUBLIC_URL?? "" // Usually empty for Vite, but supports custom deployments.
}`,
});
```
5. Start the development server:
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```
6. Open your browser and navigate to the URL displayed in the terminal (typically [http://localhost:5173](http://localhost:5173)). You’ll see the PDF document rendered in the viewer.
## Next steps
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.
## Troubleshooting
If you encounter issues, refer to the [common issues](https://www.nutrient.io/guides/web/troubleshooting/common-issues.md) guide.
> **Note for developers using AI coding assistants**: To get accurate troubleshooting help, copy the content from the [troubleshooting](https://www.nutrient.io/guides/web/troubleshooting/common-issues.md) guide and include it in your prompt, along with your specific error.
---
## Related pages
- [Get started with Web SDK](/sdk/web/getting-started.md)
- [Choose your Web SDK setup](/sdk/web/getting-started/deployment-options.md)
- [Add PDF functionality with React + Vite](/sdk/web/getting-started/react-vite.md)
- [Add PDF functionality with Next.js](/sdk/web/getting-started/nextjs.md)