System Requirements for Running Convert Conversions Locally

You need Bun ≥ 1.0, Git with submodule support, and a modern WebAssembly-capable browser to run Convert locally; all conversion engines are WebAssembly-based, so no native codecs or system binaries are required.

The p2r3/convert repository is a pure-web, client-side file conversion suite that performs all processing in the browser using WebAssembly. Understanding the system requirements for running Convert conversions locally ensures you can deploy the development server and WASM engines correctly without installing heavy native dependencies.

Core System Requirements

Bun JavaScript Runtime (≥ 1.0)

Convert requires Bun as its JavaScript runtime and package manager. According to README lines 44-48, Bun handles dependency installation via bun install and runs the Vite development server using bunx vite. Install Bun from bun.sh before proceeding.

Git with Submodule Support

The repository pulls in external format-handler submodules that are essential for conversion functionality. As noted in README line 45, you must clone recursively using git clone --recursive or run git submodule update --init --recursive after a standard clone.

WebAssembly-Capable Browser

All conversions execute client-side using WebAssembly (WASM) engines. You need a modern browser that supports WebAssembly, including recent versions of Chrome, Edge, Firefox, or Safari. The WASM assets are served from /convert/wasm/ and dynamically loaded by handlers such as [src/handlers/FFmpeg.ts](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts#L15-L36). No browser plugins or external codecs are necessary.

Step-by-Step Local Installation

Follow these commands to set up Convert on your local machine:

1. Clone the repository with submodules:

git clone --recursive https://github.com/p2r3/convert
cd convert

2. Install JavaScript dependencies:

bun install

3. Start the development server:

bunx vite

The dev server opens on http://localhost:5173 by default. Navigate to this URL in your browser, drag a file onto the interface, select an output format, and click Convert. The conversion executes entirely in your browser using the WASM engines defined in [src/handlers/FFmpeg.ts](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts), [src/handlers/ImageMagick.ts](https://github.com/p2r3/convert/blob/master/src/handlers/ImageMagick.ts), and [src/handlers/sqlite.ts](https://github.com/p2r3/convert/blob/master/src/handlers/sqlite.ts).

Optional Requirements for Cache Generation

While not required for basic operation, pre-generating the format-list cache requires Chromium or headless Chrome. The [buildCache.js](https://github.com/p2r3/convert/blob/master/package.json#L16) script uses Puppeteer—listed in devDependencies in [package.json](https://github.com/p2r3/convert/blob/master/package.json#L16)—to generate the cache. Puppeteer downloads a compatible Chromium binary automatically, but your host OS must support running it (Linux glibc, macOS, or Windows).

Alternatively, generate the cache manually by starting the dev server, opening the browser console (F12), and running:

printSupportedFormatCache()  // Returns JSON string

Save the output to cache.json in the project root to speed up subsequent startups.

Docker Deployment Alternative

If you prefer not to install Bun locally, Convert provides a containerized environment. As detailed in README lines 56-66, the Debian-based Docker image includes Chromium, FFmpeg-WASM, ImageMagick-WASM, and all necessary dependencies.

Run the container using Docker Compose:

docker compose -f docker/docker-compose.yml up -d

The service becomes available at http://localhost:8080/convert/. This approach requires only Docker and a browser—no local Bun installation or native binaries.

WebAssembly Architecture and Native Code

Convert eliminates the need for system-level codecs through WASM modules. The entry point in [src/main.ts](https://github.com/p2r3/convert/blob/master/src/main.ts) initializes the UI and conversion graph, while [vite.config.js](https://github.com/p2r3/convert/blob/master/vite.config.js) configures static asset locations.

You can interact with these WASM engines programmatically. For example, converting audio using the FFmpeg handler directly requires only the browser—no native ffmpeg binary:

import { FFmpeg } from "@ffmpeg/ffmpeg";

async function wavFromMp3(mp3Bytes: Uint8Array): Promise<Uint8Array> {
  const ffmpeg = new FFmpeg();
  await ffmpeg.load({ coreURL: "/convert/wasm/ffmpeg-core.js" });
  await ffmpeg.writeFile("in.mp3", mp3Bytes);
  await ffmpeg.exec(["-i", "in.mp3", "-f", "wav", "out.wav"]);
  const wav = await ffmpeg.readFile("out.wav");
  await ffmpeg.terminate();
  return new Uint8Array(wav);
}

This function works in any WebAssembly-capable browser, loading the core from /convert/wasm/ffmpeg-core.js as referenced in [src/handlers/FFmpeg.ts](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts#L15-L36).

Summary

• Bun ≥ 1.0 is mandatory for dependency management and running the Vite development server
• Git with submodules is required to fetch external format handlers documented in the repository
• Modern browsers with WebAssembly support handle all conversions; no native FFmpeg, ImageMagick, or SQLite binaries are needed
• Chromium is only required for the optional buildCache.js script that uses Puppeteer
• Docker offers a self-contained alternative that bundles all dependencies including the Debian-based image configuration

Frequently Asked Questions

Do I need to install FFmpeg or ImageMagick on my system?

No. Convert uses WebAssembly builds of FFmpeg and ImageMagick that execute entirely within the browser. As implemented in [src/handlers/FFmpeg.ts](https://github.com/p2r3/convert/blob/master/src/handlers/FFmpeg.ts#L15-L36), the application loads WASM assets from /convert/wasm/ and performs conversions client-side without accessing native system binaries.

Can I run Convert on Windows, macOS, and Linux?

Yes. Convert supports any operating system capable of running Bun and a modern web browser. The optional Docker deployment works cross-platform, and the WebAssembly engines execute identically across all supported browsers regardless of the host operating system.

Is Bun strictly required, or can I use Node.js?

The project is specifically configured for Bun. The README explicitly documents bun install and bunx vite as the standard commands for serving assets. While Node.js might function in some scenarios, Bun is the only officially supported runtime for local development.

Does Convert require an internet connection to perform conversions?

No. Once the application and WASM binaries are cached by the browser, all conversions happen offline. The only online requirement is the initial load of the web application and WASM assets from the local development server or the initial Docker pull.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}