integrate-file-viewer

Integrate CogniteFileViewer

Add CogniteFileViewer to this Flows app to preview CDF files (PDF, image, text).

Dependencies

The file-viewer library files (copied in Step 2) require this npm package:

pdfjs-dist ships as a dependency of react-pdf at the correct version — do not install it separately. react and @cognite/sdk are assumed to already be present in Flows apps.

Your job

Complete these steps in order. Read each file before modifying it.

Step 1 — Understand the app

Read these files before touching anything:

• package.json — detect package manager (packageManager field or lock file) and existing deps
• vite.config.ts — understand current Vite setup
• The component where the viewer should be added

Step 2 — Copy the file-viewer source files

The file-viewer library lives in the code/ directory next to this skill file. Read and copy all files from there into src/cognite-file-viewer/ inside the app:

• code/types.ts
• code/mimeTypes.ts
• code/fileResolution.ts
• code/useViewport.ts
• code/useFileResolver.ts
• code/useDocumentAnnotations.ts
• code/DocumentAnnotationOverlay.tsx
• code/CogniteFileViewer.tsx
• code/index.ts

The PDF.js worker is configured inside CogniteFileViewer.tsx — no separate consumer setup is needed.

Step 3 — Install dependencies

Install react-pdf (see Dependencies above) using the app's package manager:

• pnpm → pnpm add react-pdf@^9.1.1
• npm → npm install react-pdf@^9.1.1
• yarn → yarn add react-pdf@^9.1.1

pnpm users: pnpm's strict linking may prevent the browser from resolving pdfjs-dist. Either add pdfjs-dist as a direct dependency (pnpm add pdfjs-dist), or add public-hoist-pattern[]=pdfjs-dist to .npmrc.

Step 4 — Configure Vite

Add optimizeDeps.exclude: ['pdfjs-dist'] to vite.config.ts to prevent Vite from pre-bundling pdfjs-dist (which breaks the worker):

export default defineConfig({
  // ... existing config ...
  optimizeDeps: {
    exclude: ['pdfjs-dist'],
  },
});

Step 5 — Use the component

Import and render CogniteFileViewer from the locally copied files:

import

Get the sdk from the useDune() hook (already available in every Flows app):

Supported file types

Minimal usage

This is all you need — zoom, pan, and touch gestures are handled internally:

The component needs a defined height. If the parent has no explicit height, the viewer will collapse to zero. Always set a height via style, className, or the parent container.

File source

Pass any of three source types:

Prefer instanceId when available — it's the only source type that enables the diagram annotation overlay. When listing files via sdk.files.list(), check file.instanceId first:

Full props reference

Tips & tricks

Reset page, zoom and rotation when the source changes. The component does not reset these automatically when you switch files — do it yourself:

Gate pagination UI on numPages > 0. onDocumentLoad only fires for PDFs. Don't render pagination controls until you know there are pages to paginate:

Annotation click → navigate to linked file. annotation.linkedResource contains the space and externalId of the linked CDF instance. Match it against file.instanceId to navigate:

Touch support is built in. Two-finger pinch-to-zoom and two-finger drag-to-pan work on touch devices automatically. No configuration needed.

Pan is middle-click drag (when zoomed in) on desktop. Left-click remains free for annotation clicks and text selection.

Ctrl/Cmd + wheel zooms toward the cursor — also built in. Wire zoom/onZoomChange if you want programmatic zoom buttons or to persist zoom state; otherwise it works fully uncontrolled.

renderOverlay receives original page dimensions (originalWidth, originalHeight) so you can set up an SVG viewBox in the original coordinate space. Paths drawn in PDF-point or image-pixel coordinates will map correctly to the rendered page at any zoom level.

Common pitfalls