Adding a New Converter

ConvertX is designed to be easily extensible. All converter logic resides in src/converters/.

Converter Module Structure

To add a new tool (e.g., mytool), create a file src/converters/mytool.ts. It must export two things:

1. properties: An object defining compatible input/output formats.
2. convert: An async function that executes the command.

Example Implementation

import { execFile as execFileOriginal } from "node:child_process";
import { ExecFileFn } from "./types";

// 1. Define supported formats
export const properties = {
  from: {
    category_name: ["input_ext1", "input_ext2"],
  },
  to: {
    category_name: ["output_ext1", "output_ext2"],
  },
};

// 2. Define the conversion function
export function convert(
  filePath: string,
  fileType: string,
  convertTo: string,
  targetPath: string,
  options?: unknown,
  execFile: ExecFileFn = execFileOriginal, // Allow injection for testing
): Promise<string> {
  return new Promise((resolve, reject) => {
    // construct your command arguments
    const args = ["-i", filePath, "-o", targetPath];

    execFile("my-cli-tool", args, (error, stdout, stderr) => {
      if (error) {
        reject(`error: ${error}`);
        return;
      }
      // Log output if necessary
      if (stdout) console.log(stdout);

      resolve("Done");
    });
  });
}

Registering the Converter

Once the file is created, you must register it in src/converters/main.ts:

1. Import your module:

   import { convert as convertMyTool, properties as propertiesMyTool } from "./mytool";

2. Add it to the properties object:

   const properties = {
     // ... existing converters
     mytool: {
       properties: propertiesMyTool,
       converter: convertMyTool,
     },
   };

System Dependencies

If your converter requires a system binary (e.g., my-cli-tool), you must add it to the Dockerfile. Look for the apt-get install section in the release stage and add your package there.