npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@dukeofwest/universal-file-preview

v0.5.0

Published

Zero-dependency browser previews for DOCX, XLSX, PPTX, OpenDocument text, spreadsheets and presentations, and images, in TypeScript. Optional Web Worker parsing, strict Content Security Policy and Trusted Types support.

Readme

Universal File Preview

npm version MIT license

Open the live Angular, React and Vue demo — try a framework integration with your own file or download a sample document.

Browser-based TypeScript previews for common image formats and selected content from DOCX, XLSX, PPTX, and OpenDocument spreadsheet (ODS), text (ODT) and presentation (ODP) files. The library provides file loading, format detection, a typed viewer lifecycle, and a renderer registry. Its ZIP, DEFLATE, XML, document parsing, and rendering code is implemented in this project; it does not depend on third-party document parsing or rendering packages.

Features

  • Preview GIF, PNG, JPEG, WebP, and sanitized SVG using browser image decoding.
  • Render implemented subsets of DOCX, XLSX, PPTX, ODS/OTS/FODS, ODT/OTT/FODT and ODP/OTP/FODP in the browser.
  • Load from a File/Blob, ArrayBuffer, Uint8Array, or a URL fetched by the browser.
  • Replace the current file, zoom or fit the preview, download loaded bytes, and clean up renderer resources.
  • Add format handlers through a renderer registry.
  • Apply default viewer styles inside the viewer root; optionally import the package CSS entry.
  • Limit file size, ZIP entry size and count, and XML size, reject unsafe ZIP paths, and return typed preview errors.

The supported-format matrix lists what is detected, parsed, rendered, and covered by automated tests. The Office renderers are partial implementations and do not claim pixel-perfect compatibility with Microsoft Office.

Quick start

Install the package with npm install @dukeofwest/universal-file-preview as described in Installation. The following example uses a browser file input and the public FilePreviewer API:

import { FilePreviewer } from "@dukeofwest/universal-file-preview";

const container = document.querySelector<HTMLElement>("#viewer");
const input = document.querySelector<HTMLInputElement>("#file");
if (!container || !input) throw new Error("Viewer elements are missing.");

const preview = new FilePreviewer({
  container,
  file: { name: "welcome.svg", source: new Blob(["<svg></svg>"], { type: "image/svg+xml" }) },
});
await preview.open();

input.addEventListener("change", async () => {
  const file = input.files?.[0];
  if (!file) return;
  try {
    await preview.load({ name: file.name, source: file, mimeType: file.type });
  } catch (error) {
    console.error("Could not preview file", error);
  }
});

Call preview.destroy() from the owning UI's cleanup hook when the viewer is removed.

See Getting started for remote files, byte buffers, error handling, switching files, and custom renderers.

Angular, React and Vue

The framework examples are independent applications that consume the published npm package. They do not import the library source or add document-rendering dependencies. Each example uses a framework-managed element as the viewer container, passes a browser File to FilePreviewer, handles rejected loads, and calls destroy() when the viewer is cleared or the component is removed. Import the optional package stylesheet with @dukeofwest/universal-file-preview/styles.css.

Install the package in the framework application:

npm install @dukeofwest/universal-file-preview

The public integration shape is the same in each framework:

import { FilePreviewer } from "@dukeofwest/universal-file-preview";

const preview = new FilePreviewer({
  container: previewElement,
  file: { name: file.name, source: file, mimeType: file.type },
});
await preview.open();
// On clear, replacement, or component teardown:
preview.destroy();

In Angular, call this from a standalone component and destroy the instance in ngOnDestroy. In React, keep the host and instance in refs and destroy it from effect cleanup. In Vue 3, keep the instance in a shallowRef and destroy it in onBeforeUnmount. Catch errors from open() or load(); the viewer also displays its own loading and error status.

Angular quick start

import { Component, ElementRef, OnDestroy, ViewChild } from "@angular/core";
import { FilePreviewer } from "@dukeofwest/universal-file-preview";

@Component({ standalone: true, template: `<div #host></div>` })
export class PreviewComponent implements OnDestroy {
  @ViewChild("host", { static: true }) host!: ElementRef<HTMLDivElement>;
  private preview: FilePreviewer | null = null;

  async openFile(file: File): Promise<void> {
    this.preview?.destroy();
    this.preview = new FilePreviewer({ container: this.host.nativeElement, file: { name: file.name, source: file, mimeType: file.type } });
    try { await this.preview.open(); } catch (error: unknown) { console.error("Preview failed", error); }
  }

  ngOnDestroy(): void { this.preview?.destroy(); }
}

React quick start

import { useEffect, useRef } from "react";
import { FilePreviewer } from "@dukeofwest/universal-file-preview";

function Preview() {
  const host = useRef<HTMLDivElement>(null);
  const preview = useRef<FilePreviewer | null>(null);
  useEffect(() => () => preview.current?.destroy(), []);

  async function openFile(file: File): Promise<void> {
    const container = host.current;
    if (!container) return;
    preview.current?.destroy();
    const instance = new FilePreviewer({ container, file: { name: file.name, source: file, mimeType: file.type } });
    preview.current = instance;
    try { await instance.open(); } catch (error: unknown) { console.error("Preview failed", error); }
  }

  return <div ref={host} />;
}

Vue 3 quick start

import { onBeforeUnmount, ref, shallowRef } from "vue";
import { FilePreviewer } from "@dukeofwest/universal-file-preview";

const host = ref<HTMLDivElement | null>(null);
const preview = shallowRef<FilePreviewer | null>(null);
onBeforeUnmount(() => preview.value?.destroy());

async function openFile(file: File): Promise<void> {
  const container = host.value;
  if (!container) return;
  preview.value?.destroy();
  const instance = new FilePreviewer({ container, file: { name: file.name, source: file, mimeType: file.type } });
  preview.value = instance;
  try { await instance.open(); } catch (error: unknown) { console.error("Preview failed", error); }
}

These are integration examples, not official framework adapter packages. See format support for the actual renderer coverage and limitations.

Try the demo

The framework demo selector hosts the actual Angular, React, and Vue applications at dukeofwest.github.io/universal-file-preview. The live site includes downloadable sample files so you can try each example without preparing your own documents.

The existing local library demo can still be run from a repository checkout:

npm ci
npm run build
npm run demo

Then open http://127.0.0.1:4173/ and choose an image, DOCX, XLSX, PPTX, ODS, FODS, ODT, FODT, ODP, or FODP file.

See live demo and Pages setup for deployment status and the local framework site preview instructions.

Supported formats

| Format | Current implementation | | --- | --- | | GIF, PNG, JPEG/JPG, WebP | Browser-native image decoding; SVG is sanitized before image decoding. | | DOCX | Partial Word text, styles, tables, numbering, headers/footers, page setup, and selected images/drawings. No automatic pagination. | | XLSX | Styled worksheet grid with many cell, number, drawing, conditional-format, table, and slicer features. Charts and many formulas are not supported. | | ODS, OTS, FODS | OpenDocument spreadsheets in the same worksheet grid: typed values with the producer's saved display text, styles, number formats, merges, hidden data, comments, links, and saved view settings. Formulas are not recalculated; charts, images, and conditional formatting are not shown, and a notice lists what is missing. | | PPTX | Slide text, layout/theme/master content, shapes, images, tables, backgrounds, and navigation, with Office fidelity gaps. | | PDF, DOC, XLS, PPT | Detection only. No built-in parser or renderer. |

For detailed coverage, test status, and limitations, see Supported formats.

API and configuration

The main entry point is FilePreviewer. Its options include container, file, toolbar, zoom, download, maxFileSize, and registry. The viewer exposes open(), load(file), setZoom(value), fitToWidth(), fitToPage(), and destroy(). See API reference for public exports and exact types.

The package injects its scoped styles by default. Import @dukeofwest/universal-file-preview/styles.css when the prefixed stylesheet classes are also needed outside the viewer root.

Architecture

The flow is file source → bounded byte loading → signature/metadata detection → format parser → typed document model → registered renderer → DOM/SVG output. FilePreviewer owns the lifecycle and common controls. The ZIP/DEFLATE reader and XML parser are project code; image codecs and DOM/fetch APIs are supplied by the browser. See Architecture.

Browser requirements and framework compatibility

This is a browser package and uses browser DOM, Blob, URL.createObjectURL, fetch, and related APIs. The emitted JavaScript target is ES2022. The project does not yet publish a tested browser-version compatibility matrix. Development CI currently uses Node.js 22; a minimum supported development Node version has not been declared.

The public API is framework-agnostic. The repository includes tested Angular, React, and Vue integration examples, but does not publish framework-specific adapter packages. Use the browser lifecycle API from your framework's mount and cleanup hooks. The examples build against the current published package version.

Security and privacy

Local file sources are read in the browser and are not uploaded by this library. URL sources are fetched by the browser and remain subject to CORS and your application’s network policies. SVG, including SVG embedded in Office files, is restricted to an allowlist; external OOXML relationships are not followed. Inputs, decompression, calculation, images, and the parsed document have size and work limits. By default, document parsing runs on the main thread, so a large or crafted file can make the page unresponsive for several seconds; the optional worker mode parses documents in a Web Worker with a timeout instead. Read Security, including its deployment guidance, before previewing untrusted files.

Limitations

  • DOCX, XLSX, PPTX, ODS, ODT and ODP are partial implementations; visual and feature fidelity varies by file.
  • OpenDocument drawings (.odg), charts, formulas and databases are not supported.
  • There is no built-in PDF or legacy binary Office renderer.
  • Browser rendering and real-file visual comparisons are not covered by the current automated test suite.
  • Remote resources require CORS permission. ZIP64 and encrypted OOXML and OpenDocument packages are unsupported.
  • Font availability and image decoding depend on the browser and host system.

See Troubleshooting and Supported formats.

Development and validation

npm ci
npm run build
npm test
npm run typecheck
npm pack --dry-run

Tests use Node’s built-in test runner and synthetic parser fixtures. TypeScript is a development-only dependency; there are no runtime dependencies. See Development and Testing.

Contributing

Read CONTRIBUTING.md before making changes. The implementation must continue using the project’s own document parsing and rendering engine; do not add third-party document parsers or renderers.

License

MIT. See LICENSE.

Documentation

Repository and support