avatar64


A bulletproof, tiny, browser-only utility for profile pictures:

* Convert an image File into WebP and return plain Base64 text
* Convert Base64 text (or a full data URL) back into a safe value
* Convert Base64 text back into a PNG File object for uploads or downloads

No UI. No storage. No backend. Just conversion and display.

---

✨ Features

- 🛡️ Bulletproof - Comprehensive error handling and input validation
- 🪶 Lightweight - Zero dependencies, minimal bundle size
- 🔒 Safe - Built-in safety limits prevent browser freezing
- 📦 TypeScript - Full type definitions included
- 🎯 Focused - Does one thing exceptionally well
- ⚡ Fast - Optimized WebP conversion with high-quality output
- 🔄 Reversible - Convert base64 back to PNG files for uploads

---

📦 Install

``bash
npm install avatar64
`

`bash
yarn add avatar64
`

`bash
pnpm add avatar64
`

---

⚠️ Browser-only

This package uses Canvas API for image processing.
It must run in the browser.

> Importing or executing conversion functions on the server (Node.js / SSR) will throw an error with a clear message.

---

🚀 Quick Start

$3

`ts
import { fileToWebpBase64 } from "avatar64";

const input = document.querySelector("#file")!;
const output = document.querySelector("#out")!;

input.addEventListener("change", async () => {
const file = input.files?.[0];
if (!file) return;

try {
const { base64, width, height, decodedBytes } = await fileToWebpBase64(file, {
maxSize: 256,
quality: 0.8,
});

// Plain base64 text (NO data: prefix)
output.value = base64;
console.log(Converted to ${width}x${height}, ${decodedBytes} bytes);
} catch (error) {
console.error("Conversion failed:", error.message);
}
});
`

$3

`ts
type ConvertOptions = {
maxSize?: number; // default: 256px, set 0 to keep original size
quality?: number; // default: 0.8 (range: 0.1 to 1.0)
allowedMime?: string[]; // default: ["image/png", "image/jpeg", "image/webp", "image/gif"]
maxInputBytes?: number; // default: 6MB (6 1024 1024)
};
`

$3

`ts
type ConvertResult = {
base64: string; // Plain base64 text (NO data: prefix)
dataUrl: string; // Full data URL for immediate preview
width: number; // Output dimensions
height: number;
decodedBytes: number; // Exact size of WebP payload
};
`

---

🖼️ Show: Base64 → Image

$3

`ts
import { base64ToImgSrc } from "avatar64";

try {
img.src = base64ToImgSrc(base64Text);
// → data:image/webp;base64,...
} catch (error) {
console.error("Invalid base64:", error.message);
}
`

$3

`ts
import { showBase64InImage } from "avatar64";

try {
showBase64InImage(img, base64Text);
} catch (error) {
console.error("Failed to display image:", error.message);
}
`

$3

`ts
type ShowOptions = {
mimeFallback?: string; // default: "image/webp"
stripWhitespace?: boolean; // default: true
maxBase64Chars?: number; // default: 3,000,000
maxDecodedBytes?: number; // default: 2MB (2 1024 1024)
};
`

---

🔄 Convert: Base64 → PNG File

$3

`ts
import { base64ToPngFile } from "avatar64";

try {
// Convert base64 back to a PNG File object
const pngFile = await base64ToPngFile(base64Text, "avatar.png");

// Now you can upload it to your server
const formData = new FormData();
formData.append("avatar", pngFile);

await fetch("/api/upload", {
method: "POST",
body: formData,
});

console.log(✓ Created PNG file: ${pngFile.name}, ${pngFile.size} bytes);
} catch (error) {
console.error("Conversion failed:", error.message);
}
`

$3

`ts
import { downloadBase64AsPng } from "avatar64";

try {
// Trigger immediate browser download
await downloadBase64AsPng(base64Text, "my-avatar.png");
console.log("✓ Download started");
} catch (error) {
console.error("Download failed:", error.message);
}
`

---

🔧 API Reference

$3

Converts an image File to WebP format and returns base64 text.

Parameters:
- file: File - Image file to convert
- options?: ConvertOptions - Optional conversion settings

Returns: Promise

Throws: Detailed error if file is invalid, too large, unsupported type, or conversion fails

---

$3

Converts base64 text or data URL to a safe value.

Parameters:
- base64OrDataUrl: string - Plain base64 or full data URL
- options?: ShowOptions - Optional display settings

Returns: string - Safe data URL for image src

Throws: Detailed error if input is invalid, corrupted, or exceeds safety limits

---

$3

Convenience function to directly set an image element's src.

Parameters:
- img: HTMLImageElement - Target image element
- base64OrDataUrl: string - Plain base64 or full data URL
- options?: ShowOptions - Optional display settings

Returns: void

Throws: Detailed error if element is invalid or base64 is corrupted

---

$3

Converts base64 text or data URL to a PNG File object.

Parameters:
- base64OrDataUrl: string - Plain base64 or full data URL
- filename?: string - Output filename (default: "image.png")
- options?: ShowOptions - Optional display settings

Returns: Promise - PNG File object ready for upload

Throws: Detailed error if input is invalid or conversion fails

Use cases:
- Upload base64 images to servers that require File objects
- Convert stored base64 back to files for FormData
- Programmatic file handling in web apps

---

$3

Converts base64 to PNG and triggers browser download.

Parameters:
- base64OrDataUrl: string - Plain base64 or full data URL
- filename?: string - Download filename (default: "image.png")
- options?: ShowOptions - Optional display settings

Returns: Promise

Throws: Detailed error if input is invalid or download fails

Use cases:
- "Save As" / "Download" buttons for profile pictures
- Export user-generated images
- Backup/download functionality

---

$3

Calculate the exact decoded byte size of a base64 string.

Parameters:
- base64: string - Base64 string to measure

Returns: number - Exact decoded bytes (0 if invalid)

---

🛡️ Safety Features

- ✅ Validates all inputs (File type, MIME, size, dimensions)
- ✅ Protects against corrupted or malicious files
- ✅ Prevents browser freezing with size limits
- ✅ Timeout protection for slow image loading
- ✅ Proper resource cleanup (blob URLs, canvas)
- ✅ Descriptive error messages for debugging
- ✅ Handles edge cases (empty files, invalid dimensions)

$3

| Limit | Default | Purpose |
|-------|---------|---------|
| maxInputBytes | 6 MB | Reject oversized input files |
| maxSize | 256px | Resize large images |
| maxBase64Chars | 3,000,000 | Prevent massive base64 strings |
| maxDecodedBytes | 2 MB | Limit decoded image size |
| Image dimensions | 16384×16384 | Prevent canvas errors |
| Load timeout | 30 seconds | Prevent hanging |

---

📝 Notes & Limitations

- Base64 inflates size by ~33% compared to binary
- Output format for conversion is always WebP for optimal size/quality
- PNG conversion uses lossless encoding with full alpha channel support
- Browser support requires Canvas API (all modern browsers)
- Designed for avatars - profile pictures, not large photos
- No server-side support - browser environment required
- WebP encoding must be supported by browser (widely supported)

---

💡 Use Cases

- User profile picture uploads
- Avatar selection interfaces
- Image preview before upload
- Client-side image optimization
- Progressive web apps with offline image handling
- Chat applications with avatar display
- Account settings pages
- Download/export functionality for user images
- Converting stored base64 back to files for re-upload

---

🔄 Example: Complete Upload Flow

`ts
import { fileToWebpBase64, base64ToImgSrc } from "avatar64";

async function handleAvatarUpload(file: File) {
try {
// Convert to WebP base64
const result = await fileToWebpBase64(file, {
maxSize: 256,
quality: 0.85,
});

// Preview locally
const preview = document.querySelector("#preview")!;
preview.src = result.dataUrl;

// Send plain base64 to your API
await fetch("/api/profile/avatar", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ avatar: result.base64 }),
});

console.log(✓ Uploaded ${result.width}×${result.height} avatar);
} catch (error) {
console.error("Upload failed:", error.message);
alert(Failed to upload avatar: ${error.message});
}
}

// Later, display stored avatar
function displayAvatar(base64: string) {
const img = document.querySelector("#avatar")!;
try {
img.src = base64ToImgSrc(base64);
} catch (error) {
console.error("Failed to display avatar:", error.message);
img.src = "/default-avatar.png"; // fallback
}
}
`

---

🔄 Example: Base64 to PNG Conversion Flow

`ts
import { base64ToPngFile, downloadBase64AsPng } from "avatar64";

// Example 1: Upload stored base64 as a file
async function uploadStoredAvatar(base64: string) {
try {
// Convert base64 to PNG File
const pngFile = await base64ToPngFile(base64, "avatar.png");

// Upload using FormData
const formData = new FormData();
formData.append("avatar", pngFile);

await fetch("/api/upload", {
method: "POST",
body: formData,
});

console.log(✓ Uploaded ${pngFile.name});
} catch (error) {
console.error("Upload failed:", error.message);
}
}

// Example 2: Download button functionality
async function handleDownloadClick(base64: string) {
try {
await downloadBase64AsPng(base64, "my-profile-pic.png");
console.log("✓ Download started");
} catch (error) {
console.error("Download failed:", error.message);
alert(Failed to download: ${error.message});
}
}

// Example 3: Convert and get file for programmatic use
async function processAvatar(base64: string) {
try {
const pngFile = await base64ToPngFile(base64, "processed-avatar.png");

// Use the File object however you need
console.log(File created: ${pngFile.name});
console.log(Size: ${pngFile.size} bytes);
console.log(Type: ${pngFile.type});

// Can be used with any API that accepts File objects
return pngFile;
} catch (error) {
console.error("Processing failed:", error.message);
throw error;
}
}
``

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

MIT © Binidu01

---

🔗 Links

- GitHub Repository
- npm Package
- Report Issues

---

Made with ❤️ for the web