File Converter

A robust, type-safe, and highly performant file conversion utility built with pure TypeScript.

⚠️ Note: This package is Browser Compatible Only for now. It is designed to run 100% client-side in the browser (e.g., React, Next.js, Vanilla JS) to ensure maximum privacy with zero server uploads. Node.js support is planned for a future release.

✨ Features

• Browser Compatible Only (For Now): Runs 100% client-side. Your files never leave the user's device.
• React & Frontend Ready: Seamlessly integrates with React, Next.js, Vue, and vanilla frontend applications.
• Adapter Pattern Architecture: Built with a scalable Adapter Pattern, making it incredibly easy to plug in new file format converters without touching core logic.

📂 Supported Formats (Current)

Thanks to our Adapter Pattern, the package currently supports the following conversions out of the box:

| Input Format | Output Formats Supported | | :--------------------------------------------------------------------- | :------------------------------------------ | | Images (.jpg, .jpeg, .png, .webp, .gif, .bmp, .tiff) | Any other supported Image format, or .pdf | | Apple HEIC/HEIF (.heic, .heif) | .jpg, .png, .webp | | PDF (.pdf) | .jpg, .png (First page extraction) |

(More adapters for formats like DOCX, AVIF, and multi-page PDF rendering are actively being developed!)

📦 Installation

Install the package via your preferred package manager:

# Using pnpm (recommended)
pnpm add @sikandarmoyaldev/file-converter

# Using npm
npm install @sikandarmoyaldev/file-converter

# Using yarn
yarn add @sikandarmoyaldev/file-converter

🚀 Usage

Core API (Vanilla JS/TypeScript)

import { converter } from "@sikandarmoyaldev/file-converter";

// Convert a single file
const blob = await converter.convert(file, "png", { quality: 0.9 });

// Convert multiple files
const blobs = await converter.convertMultiple(files, "jpeg", { quality: 0.8 });

// Get supported output formats for a file type
const formats = converter.getSupportedOutputFormats("image/png");

React: Single File

import { useConverter } from "@sikandarmoyaldev/file-converter/react";

function SingleFileConverter() {
    const { progress, status, convertedBlob, error, convert, reset } = useConverter();

    const handleConvert = async (file: File) => {
        await convert(file, "png", { quality: 0.9 });
    };

    return (
        <div>
            <input
                type="file"
                onChange={(e) => e.target.files?.[0] && handleConvert(e.target.files[0])}
            />

            {status === "converting" && <p>Progress: {progress}%</p>}
            {status === "completed" && convertedBlob && (
                <a href={URL.createObjectURL(convertedBlob)} download="converted.png">
                    Download
                </a>
            )}
            {status === "error" && <p>Error: {error}</p>}

            <button onClick={reset}>Reset</button>
        </div>
    );
}

React: Multiple Files

import { useConvertMultiple } from "@sikandarmoyaldev/file-converter/react";

function MultiFileConverter() {
    const {
        files,
        isConverting,
        overallProgress,
        addFiles,
        removeFile,
        updateFileFormat,
        convertAll,
        reset,
    } = useConvertMultiple();

    const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
        if (e.target.files) {
            addFiles(Array.from(e.target.files), "jpeg");
        }
    };

    return (
        <div>
            <input type="file" multiple onChange={handleFileSelect} />

            <p>Overall Progress: {overallProgress}%</p>

            {files.map((file) => (
                <div key={file.id}>
                    <span>{file.file.name}</span>
                    <span>Status: {file.status}</span>
                    <span>Progress: {file.progress}%</span>

                    <select
                        value={file.targetFormat}
                        onChange={(e) => updateFileFormat(file.id, e.target.value)}
                        disabled={isConverting}
                    >
                        <option value="jpeg">JPG</option>
                        <option value="png">PNG</option>
                        <option value="webp">WEBP</option>
                    </select>

                    <button onClick={() => removeFile(file.id)} disabled={isConverting}>
                        Remove
                    </button>

                    {file.convertedBlob && (
                        <a href={URL.createObjectURL(file.convertedBlob)} download={file.file.name}>
                            Download
                        </a>
                    )}
                </div>
            ))}

            <button onClick={() => convertAll({ quality: 0.9 })} disabled={isConverting}>
                {isConverting ? "Converting..." : "Convert All"}
            </button>

            <button onClick={reset} disabled={isConverting}>
                Clear All
            </button>
        </div>
    );
}

🤝 Contributing

Contributions are welcome! Please read the CONTRIBUTING.md file for details on our code of conduct, the tools we use, and the process for submitting pull requests.