ConvertX

ConvertX is a self‑hosted, web‑based file conversion engine written in TypeScript and powered by the modern Bun runtime. At its core, it exposes a RESTful API and a lightweight web UI that allow users to upload arbitrary files, select target formats, and retrieve converted outputs. The application is designed around a plug‑in architecture: each supported converter (Inkscape, libjxl, Vips, Pandoc, etc.) is wrapped in a small wrapper script that normalizes input/output handling and exposes a uniform convert(input, options) interface. This design keeps the core service agnostic to the specific binary toolchains while enabling rapid addition of new converters through simple configuration changes.

Technical Stack

• Runtime: Bun (v1.x), chosen for its fast startup, built‑in TypeScript support, and efficient HTTP server (Elysia).
• Framework: Elysia – a minimal, middleware‑driven web framework that provides type‑safe routing and automatic JSON schema generation.
• Language: TypeScript, ensuring compile‑time safety for API contracts and internal logic.
• Containerization: Docker images are built on Alpine‑based Bun containers, keeping the image size under 200 MB and making it ideal for Kubernetes or Docker‑Compose deployments.
• Persistence: Optional PostgreSQL/MySQL integration for user accounts and job metadata; otherwise a lightweight SQLite database is used by default.
• Background Processing: A simple in‑memory job queue runs on the same process, but can be swapped out for a message broker (RabbitMQ/Redis) if scaling to multiple workers is required.

Core Capabilities

• Batch Conversion: The API accepts multipart uploads and processes each file concurrently, returning a ZIP archive of all outputs.
• Password Protection: Users can specify passwords for encrypted output formats (e.g., PDF, ZIP) or to protect uploaded files from public access.
• Account Isolation: When user accounts are enabled, all conversion jobs are namespaced per user, with configurable quotas and storage limits.
• Extensible Converter Registry: Converters are defined in a JSON schema that lists supported input/output MIME types, required binaries, and optional environment variables. Adding a new converter only requires installing the binary on the host and updating this registry.
• Webhook & API: A webhook endpoint can be configured to receive job completion notifications, and the REST API exposes endpoints for job submission (POST /convert), status polling (GET /jobs/:id), and result retrieval (GET /jobs/:id/download).
• Metrics & Logging: Built‑in Prometheus metrics (job count, latency) and structured JSON logs facilitate observability in production environments.

Deployment & Infrastructure

ConvertX ships as a single Docker image, but the source code can be compiled to a native binary with Bun’s bun build. The minimal runtime footprint allows it to run on resource‑constrained devices (Raspberry Pi, NAS) or in cloud VMs. For high‑throughput scenarios, a horizontal pod autoscaler can spin up additional replicas behind an ingress controller; the stateless design means any replica can pick up queued jobs if a shared message broker is used. Persistent storage for user uploads and job outputs can be backed by NFS, cloud object stores (S3 compatible), or local disk volumes.

Integration & Extensibility

Developers can integrate ConvertX into CI/CD pipelines, document management systems, or custom web applications. The plugin system allows third‑party developers to write their own converter wrappers in any language, as long as they expose the expected CLI contract. Webhooks provide real‑time integration points for downstream services (e.g., trigger a notification once a PDF is ready). The UI itself is built with SvelteKit, making it straightforward to fork and extend the front‑end if a custom branding or workflow is needed.

Developer Experience

The repository contains comprehensive TypeScript typings for the public API, example curl commands, and a detailed README that walks through configuring users, setting up converter binaries, and exposing the service behind HTTPS. Community support is active on GitHub Discussions, with frequent issue triage and pull‑request reviews. Licensing under MIT ensures no vendor lock‑in, while the open‑source nature means contributors can audit security and performance characteristics directly.

Use Cases

• Enterprise Document Conversion: Convert internal Word, ODT, and PDF files to web‑friendly formats (HTML, Markdown) for knowledge bases.
• Media Asset Management: Batch‑convert raw images and vector graphics (SVG, Inkscape) into optimized formats for web delivery.
• E‑book Publishing: Leverage Calibre and Pandoc to transform manuscripts between EPUB, MOBI, and PDF.
• Automated Testing: Use the API in test suites to verify that conversion pipelines produce expected outputs for new releases.
• Educational Platforms: Provide students with a self‑hosted conversion tool to submit assignments in multiple formats without relying on external services.

Advantages

• Performance: Bun’s JIT and Elysia’s lightweight routing give sub‑100 ms response times for small jobs, outperforming many Node.js equivalents.
• Flexibility: The converter registry abstracts away binary differences, allowing a single codebase to support over 1,000 file formats.
• Licensing & Privacy: Self‑hosting guarantees that all conversion data stays on premises, a critical requirement for