ConvertX is a self-hosted file conversion platform designed for individuals and organizations seeking full control over their file conversions. It eliminates dependency on cloud-based converters by running entirely on your infrastructure, supporting a vast array of formats from PDFs and DOCX to HEIC, SVG, 3D models, and video files. Built with TypeScript, Bun, and Elysia, it provides a secure, scalable solution for teams needing to convert files internally.
The application leverages over 17 external conversion tools including FFmpeg, ImageMagick, LibreOffice, and Calibre, and is deployed via Docker with support for multi-user accounts, password protection, and automated file cleanup. It integrates with modern web technologies like TailwindCSS and offers a responsive UI with history tracking and batch processing.
What You Get
- 1000+ Format Support - Converts documents, images, videos, 3D models, and data files using 17+ underlying tools like FFmpeg, ImageMagick, LibreOffice, and Pandoc.
- Multi-User Accounts - Supports registered users with password protection and role-based access to prevent unauthorized conversions.
- Batch File Conversion - Process multiple files simultaneously with a single upload, improving workflow efficiency for bulk operations.
- Self-Hosted Deployment - Deploy via Docker using GitHub Container Registry or Docker Hub with full control over data and privacy.
- Automated File Cleanup - Automatically deletes converted files after a configurable time (default: 24 hours) to manage storage usage.
- JWT Authentication - Uses JSON Web Tokens for secure session management; supports custom JWT_SECRET for production environments.
- HTTP/HTTPS Flexibility - Allows HTTP access in local environments via HTTP_ALLOWED=true, with secure HTTPS recommended for public use.
- FFmpeg Hardware Acceleration - Supports hardware-accelerated video conversion via FFMPEG_ARGS and FFMPEG_OUTPUT_ARGS environment variables.
- Language Localization - Configurable date formatting using BCP 47 language tags (e.g., en, pl, zh) for international users.
- Unauthenticated Mode - Allows public access without login (via ALLOW_UNAUTHENTICATED) for internal or kiosk use cases.
Common Use Cases
- Running a digital archive - A librarian converts scanned PDFs, DOCX, and EPUBs to accessible formats like plain text and HTML for preservation.
- Managing media assets for a studio - A video editor converts raw video files (MP4, MOV, AVI) to optimized web formats using FFmpeg with hardware acceleration.
- Processing academic papers - A researcher converts LaTeX files to PDF and DOCX, and HEIC images to JPEG for journal submissions.
- Internal document workflow - A legal firm converts scanned PDFs, Outlook MSG files, and Word docs to searchable PDF/A for compliance and archiving.
Under The Hood
Architecture
- Elysia-based server with modular route handlers that enforce single-responsibility principles through clean .use() separations
- Converter modules implement a consistent interface, isolating format-specific logic from HTTP routing while enabling extensible format support
- Dependency injection via optional execFile parameters enhances testability and runtime flexibility without tight coupling
- UI components are cleanly separated from styling using Tailwind CSS and Kitajs/HTML, with theming variables ensuring visual consistency
- Environment-driven configuration decouples deployment behaviors like authentication and auto-deletion from core business logic
- Monorepo structure organizes code into distinct domains—pages, converters, and components—wired through a minimal entry point
Tech Stack
- TypeScript backend powered by Elysia with built-in support for routing, authentication, and static file serving
- Frontend rendered via Kitajs/HTML with JSX-like syntax and Tailwind CSS, built with Bun for speed and efficiency
- Dockerized deployment uses a minimal Debian base with bundled conversion tools, optimized for multi-architecture compatibility
- Build and linting toolchain centered on Bun, with Biome, Knip, and ESLint enforcing code consistency and eliminating dead code
- Infrastructure as code via compose.yaml and mise.toml for reproducible environments, with automated dependency updates via Renovate
- Production-grade features include JWT authentication, environment toggles, and a hardened Docker image with minimal attack surface
Code Quality
- Extensive test coverage with robust mocking of external dependencies, ensuring reliable unit tests for conversion logic
- Strong type safety through explicit interfaces and defensive programming, handling edge cases and format validation with precision
- Modular organization separates conversion logic, utilities, and tests, promoting maintainability and code reuse
- Comprehensive error handling with descriptive messages and structured assertions for both success and failure paths
- Consistent naming, component structure, and test patterns across the codebase reflect a disciplined development workflow
- Strict TypeScript usage and absence of unnecessary type assertions indicate rigorous type discipline
What Makes It Unique
- Unified interface for 15+ specialized conversion tools, enabling cross-format transformations without external APIs
- Just-in-time Tailwind CSS generation eliminates static asset builds while preserving theme consistency in dynamic UIs
- Automated job lifecycle management with background cleanup tied to user sessions, reducing infrastructure overhead
- Real-time progress tracking via database state updates and client-side feedback during long-running conversions
- Startup-time dependency verification auto-detects missing native binaries, ensuring robust deployment validation
- Server-rendered single-page experience without client-side bundlers or SPA frameworks, delivering seamless UX with minimal overhead