▲reactivite
/packages/docs/courses/cli/skillpool/promaster/contact
all docs

$ npm view @ubuligan/file-preview-utils

Utility

@ubuligan/file-preview-utils

A lightweight TypeScript utility for converting files from Blob to Base64 and previewing images, PDFs, and other files in a new browser tab.

npm versiondownloads
npm github
$ npm install @ubuligan/file-preview-utils

@ubuligan/file-preview-utils#

A lightweight TypeScript utility package for converting files from Blob to Base64 and previewing images, PDFs, and other files in a new browser window. Works with any axios-like HTTP client for maximum flexibility.

Features#

  • 🚀 Zero dependencies - Uses native browser APIs
  • 📁 File conversion - Convert Blob objects to Base64 strings
  • 🖼️ Image preview - Display images in new browser windows
  • 📄 PDF handling - Open PDFs in browser for viewing
  • 💾 File downloads - Automatic download for other file types
  • 🔧 TypeScript support - Full type definitions included
  • 🌐 HTTP client agnostic - Works with axios, fetch wrappers, or any compatible client

Installation#

npm install @ubuligan/file-preview-utils

Quick Start#

import axios from "axios";
import { previewFile, blobToBase64 } from "@ubuligan/file-preview-utils";

// Preview a file (images open in new window, PDFs open in browser, others download)
await previewFile("/api/files/document.pdf", "document.pdf", axios);

// Convert a blob to base64
const blob = new Blob(["Hello World"], { type: "text/plain" });
const base64String = await blobToBase64(blob);

API Reference#

previewFile(url, fileName, httpClient, isEdocMainFile?)#

Opens or downloads a file from a given URL depending on its type.

Parameters:

  • url (string) - File URL to preview or download
  • fileName (string) - Desired file name for downloads
  • httpClient (HttpClient) - An axios-like HTTP client instance
  • isEdocMainFile? (boolean) - Optional flag to add { edocDocument: true } param

Behavior:

  • Images (image/*): Opens in a new browser window
  • PDFs (application/pdf): Opens in browser for viewing
  • Other files: Triggers download with specified filename

Example:

import axios from "axios";
import { previewFile } from "@ubuligan/file-preview-utils";

// Preview an image
await previewFile("/api/images/photo.jpg", "photo.jpg", axios);

// Preview a PDF
await previewFile("/api/documents/report.pdf", "report.pdf", axios);

// Download a document
await previewFile("/api/files/data.xlsx", "data.xlsx", axios);

// With edoc flag
await previewFile("/api/edoc/document.pdf", "document.pdf", axios, true);

blobToBase64(blob)#

Converts a Blob object to a Base64 string.

Parameters:

  • blob (Blob) - The Blob to convert

Returns:

  • Promise<string> - Base64 encoded string (includes data URL prefix)

Example:

import { blobToBase64 } from "@ubuligan/file-preview-utils";

// Convert file input to base64
const fileInput = document.getElementById("file") as HTMLInputElement;
const file = fileInput.files?.[0];
if (file) {
  const base64 = await blobToBase64(file);
  console.log(base64); // "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

// Convert response data to base64
const response = await axios.get("/api/image", { responseType: "blob" });
const base64 = await blobToBase64(response.data);

HTTP Client Interface#

The package works with any HTTP client that implements the HttpClient interface:

interface HttpClient {
  get<T>(
    url: string,
    config?: {
      responseType?: string;
      params?: Record<string, any>;
    }
  ): Promise<{
    status: number;
    data: T;
    headers: Record<string, string>;
  }>;
}

Using with Different HTTP Clients#

Axios (Recommended)#

import axios from "axios";
import { previewFile } from "@ubuligan/file-preview-utils";

await previewFile("/api/file.pdf", "file.pdf", axios);

Custom Fetch Wrapper#

import { previewFile } from "@ubuligan/file-preview-utils";

const fetchClient = {
  async get(url: string, config?: any) {
    const response = await fetch(url);
    return {
      status: response.status,
      data: await response.blob(),
      headers: Object.fromEntries(response.headers.entries()),
    };
  },
};

await previewFile("/api/file.pdf", "file.pdf", fetchClient);

Error Handling#

import { previewFile } from "@ubuligan/file-preview-utils";

try {
  await previewFile("/api/file.pdf", "file.pdf", axios);
} catch (error) {
  console.error("Failed to preview file:", error);
}

The previewFile function logs errors to the console when the HTTP response status is not 200.

Browser Compatibility#

  • Modern browsers with FileReader API support
  • ES2017+ for async/await syntax
  • Blob and URL APIs for file handling

Use Cases#

Document Management Systems#

// Preview user-uploaded documents
const handleFilePreview = async (fileId: string, fileName: string) => {
  await previewFile(`/api/documents/${fileId}`, fileName, axios);
};

Image Galleries#

// Display images in new windows
const showImage = async (imageUrl: string, imageName: string) => {
  await previewFile(imageUrl, imageName, axios);
};

File Conversion Utilities#

// Convert uploaded files to base64 for storage
const convertFileToBase64 = async (file: File): Promise<string> => {
  return await blobToBase64(file);
};

TypeScript Support#

This package is written in TypeScript and includes full type definitions. No additional @types packages are needed.

import {
  previewFile,
  blobToBase64,
  HttpClient,
} from "@ubuligan/file-preview-utils";

// All functions are fully typed
const client: HttpClient = axios;
const result: Promise<void> = previewFile("/api/file", "file.pdf", client);
const base64: Promise<string> = blobToBase64(new Blob());

Contributing#

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License#

MIT © Javid Salimov

Repository#

  • GitHub: https://github.com/jsznpm/file-preview
  • Issues: https://github.com/jsznpm/file-preview/issues
  • home
  • packages
  • skillpool
  • docs
  • cli
▲reactivite

// The fastest way to scaffold production-ready React apps. Built by developers, for developers.

$ npm create reactivite@latest

resources/

  • └─ documentation
  • └─ packages
  • └─ cli
  • └─ courses
  • └─ markdown
  • └─ diff
  • └─ run
  • └─ radio
  • └─ tv
  • └─ games
  • └─ about
  • └─ contact

community/

  • └─ github

© 2026 reactivite — all rights reserved