convert-ui/README.md

Convert UI

A modern, browser-based file conversion application built with Next.js 16, Tailwind CSS 4, and WebAssembly. Convert videos, images, and documents directly in your browser without uploading files to any server.

Features

• 🎬 Video Conversion - Convert between MP4, WebM, AVI, MOV, MKV, and GIF
• 🎵 Audio Conversion - Convert between MP3, WAV, OGG, AAC, and FLAC
• 🖼️ Image Conversion - Convert between PNG, JPG, WebP, GIF, BMP, TIFF, and SVG
• 📄 Document Conversion - Convert between PDF, Markdown, HTML, and Plain Text
• 🔒 Privacy First - All conversions happen locally in your browser, no server uploads
• ⚡ Fast & Efficient - Powered by WebAssembly for near-native performance
• 🎨 Beautiful UI - Modern, responsive design with dark/light theme support
• 🔍 Smart Search - Fuzzy search for quick format selection
• 📝 Conversion History - Track your recent conversions
• 🎯 Drag & Drop - Easy file upload with drag-and-drop support

Tech Stack

• Next.js 16 - React framework with App Router and static export
• React 19 - Latest React with concurrent features
• TypeScript 5 - Type-safe development
• Tailwind CSS 4 - Utility-first CSS with OKLCH color system
• FFmpeg.wasm - Video and audio conversion
• ImageMagick WASM - Image processing and conversion
• Marked - Markdown to HTML conversion
• Turndown - HTML to Markdown conversion
• DOMPurify - HTML sanitization
• jsPDF - PDF generation
• PDF.js - PDF text extraction
• docx - DOCX document generation
• mammoth - DOCX document reading
• Fuse.js - Fuzzy search for format selection
• Lucide React - Beautiful icon library

Getting Started

Prerequisites

• Node.js 22+ (managed via nvm)
• pnpm (enabled via corepack)

Installation

# Clone the repository
git clone <repository-url>
cd convert-ui

# Install dependencies
pnpm install

# Run development server
pnpm dev

Open http://localhost:3000 to view the app.

Build for Production

# Build static export
pnpm build

# Output will be in the /out directory

Project Structure

convert-ui/
├── app/                              # Next.js App Router
│   ├── layout.tsx                   # Root layout with theme
│   ├── page.tsx                     # Main page
│   └── globals.css                  # Global styles
├── components/
│   ├── converter/                   # Converter components
│   │   ├── FileConverter.tsx        # Main state manager
│   │   ├── FileUpload.tsx          # Drag-and-drop upload
│   │   ├── FormatSelector.tsx      # Format selection with search
│   │   ├── ConversionPreview.tsx   # Preview and download
│   │   └── ConversionOptions.tsx   # Format-specific options
│   ├── layout/
│   │   └── ThemeToggle.tsx         # Dark/light theme toggle
│   └── ui/                         # Reusable UI components
│       ├── Button.tsx
│       ├── Card.tsx
│       ├── Toast.tsx
│       ├── Progress.tsx
│       ├── Skeleton.tsx
│       └── Input.tsx
├── lib/
│   ├── converters/                 # Conversion services
│   │   ├── ffmpegService.ts       # Video/audio conversion
│   │   ├── imagemagickService.ts  # Image conversion
│   │   └── pandocService.ts       # Document conversion (placeholder)
│   ├── wasm/
│   │   └── wasmLoader.ts          # WASM module lazy loading
│   ├── storage/
│   │   └── history.ts             # Conversion history
│   └── utils/
│       ├── cn.ts                  # Class name utility
│       ├── fileUtils.ts           # File operations
│       ├── formatMappings.ts      # Supported formats
│       └── debounce.ts            # Debounce utility
└── types/
    └── conversion.ts              # TypeScript interfaces

Supported Formats

Video (FFmpeg)

• Input/Output: MP4, WebM, AVI, MOV, MKV, GIF

Audio (FFmpeg)

• Input/Output: MP3, WAV, OGG, AAC, FLAC

Images (ImageMagick)

• Input/Output: PNG, JPG, WebP, GIF, BMP, TIFF, SVG

Documents

• PDF → Text/Markdown - Extract text from PDF files with page-by-page processing
• Markdown/HTML/Text → PDF - Generate formatted PDF documents
• DOCX → Text/HTML/Markdown - Extract content from Word documents
• Markdown/HTML/Text → DOCX - Create formatted Word documents with headings
• Markdown → HTML - Full GitHub Flavored Markdown support with styling
• HTML → Markdown - Clean conversion with formatting preservation
• Markdown ↔ Plain Text - Strip or add basic formatting
• HTML → Plain Text - Extract text content
• Plain Text → HTML - Convert to formatted HTML document

Supported PDF Operations:

• Read PDFs and extract all text content
• Convert extracted text to Markdown or plain text
• Create PDFs from Markdown, HTML, or plain text
• Automatic pagination and formatting

Supported DOCX Operations:

• Read DOCX files and extract text, HTML, or Markdown
• Create DOCX files from Markdown with proper heading levels (H1-H3)
• Create DOCX files from HTML or plain text
• Automatic paragraph formatting and spacing

Note: Uses PDF.js for reading and jsPDF for generation. Uses mammoth for DOCX reading and docx library for generation. Lightweight JavaScript libraries (marked, turndown) used instead of Pandoc WASM for fast, reliable conversions.

How It Works

1. File Upload - Users can drag-and-drop or click to select a file
2. Format Detection - The app automatically detects the input format
3. Format Selection - Choose from compatible output formats
4. Conversion - WASM modules are loaded on-demand and process the file
5. Download - Preview and download the converted file

WASM Architecture

• Lazy Loading - WASM modules are only loaded when needed
• Memory Management - Proper cleanup after each conversion
• Progress Tracking - Real-time progress updates during conversion
• Error Handling - Graceful error handling with user-friendly messages

Browser Compatibility

• Chrome/Edge - Full support
• Firefox - Full support
• Safari - Full support (with SharedArrayBuffer)

Note: Some features require SharedArrayBuffer support. The app sets the required COOP/COEP headers for this.

Performance

• File Size Limit - 500MB (configurable)
• Conversion Speed - Varies by file size and format
  • Images: < 5s for typical files
  • Videos: Depends on length and quality
• Memory Usage - Managed automatically with cleanup

Development

Scripts

# Development server with Turbopack
pnpm dev

# Build for production
pnpm build

# Run production server
pnpm start

# Lint code
pnpm lint

Adding New Formats

1. Add format to lib/utils/formatMappings.ts
2. Implement converter in appropriate service
3. Update type definitions in types/conversion.ts

Customizing Theme

Colors are defined in app/globals.css using OKLCH color space. Modify CSS variables to change the theme:

:root {
  --primary: oklch(22.4% 0.053 285.8);
  --background: oklch(100% 0 0);
  /* ... other colors */
}

Docker Deployment

# Build Docker image
docker build -t convert-ui .

# Run container
docker run -p 80:80 convert-ui

The Dockerfile uses a multi-stage build with Nginx to serve the static export.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - See LICENSE file for details

Acknowledgments

• FFmpeg.wasm - Video/audio conversion
• ImageMagick WASM - Image processing
• Next.js - React framework
• Tailwind CSS - Styling
• Fuse.js - Fuzzy search

Support

For issues, questions, or suggestions, please open an issue on GitHub.

---

Made with ❤️ using Next.js 16 and WebAssembly