How to Define a New Operation Type in iloader: A Complete Developer Guide

To define a new operation type in iloader, implement the Operation interface in src/components/operations.ts by assigning a unique id, specifying translation keys, declaring an array of steps, and registering the corresponding translation strings in src/i18next.ts.

The open-source iloader project (nab138/iloader) models every user-facing workflow as a strongly-typed Operation object. When you define a new operation type in iloader, you work within a strict TypeScript contract that guarantees type safety and consistent UI rendering across the application.

Understanding the Operation Interface in iloader

In src/components/operations.ts, the codebase declares the Operation interface that governs all user actions. An Operation is a plain TypeScript object requiring a unique id, a titleKey for internationalization, and an array of steps. Each step must conform to the OperationStep type, containing its own id and titleKey. Optional fields like successTitleKey and successMessageKey control the completion state messaging.

Step-by-Step Guide to Define a New Operation Type in iloader

1. Create the Operation Object

Start by defining a constant that satisfies the Operation type. Choose a globally unique id (conventionally snake_case) and reference translation keys that describe the operation's purpose.

2. Define the Execution Steps

Populate the steps array with objects that implement OperationStep. Every step requires a distinct id and a titleKey pointing to a human-readable label in your translation files. The order in this array determines the sequential execution flow presented to the user.

3. Add Translation Keys

Open src/i18next.ts and insert entries for every titleKey, successTitleKey, and successMessageKey you declared. The keys must exist under the translation namespace to prevent runtime missing-key errors during UI rendering.

4. Export and Register the Operation

Export the operation constant from its module. If the UI consumes a centralized collection (such as an allOperations array), append your new operation to that list to make it available for selection.

Complete Code Example: Adding a Backup Database Operation

The following example demonstrates how to define a new operation type in iloader that performs a database backup with three distinct phases.

// src/components/operations.ts
import { Operation } from "./operations";

export const backupDatabaseOperation: Operation = {
  id: "backup_database",
  titleKey: "operations.backup_db_title",
  successTitleKey: "operations.backup_db_success_title",
  successMessageKey: "operations.backup_db_success_message",
  steps: [
    {
      id: "export",
      titleKey: "operations.backup_db_step_export",
    },
    {
      id: "compress",
      titleKey: "operations.backup_db_step_compress",
    },
    {
      id: "upload",
      titleKey: "operations.backup_db_step_upload",
    },
  ],
};

// Optional: Add to central registry
export const allOperations = [
  // ... existing operations
  backupDatabaseOperation,
];

// src/i18next.ts
export const resources = {
  en: {
    translation: {
      "operations.backup_db_title": "Backup Database",
      "operations.backup_db_success_title": "Backup Completed",
      "operations.backup_db_success_message": "Your database has been successfully backed up.",
      "operations.backup_db_step_export": "Export database",
      "operations.backup_db_step_compress": "Compress export",
      "operations.backup_db_step_upload": "Upload to storage",
    },
  },
};

Key Files and Their Roles

• src/components/operations.ts: Declares the Operation and OperationStep interfaces and houses the built-in operation constants.
• src/i18next.ts: Contains the i18next translation resources referenced by titleKey and other localization keys.
• src/update.ts: Consumes OperationUpdate objects to drive UI state changes during operation execution (if present in the codebase).

Summary

• To define a new operation type in iloader, create an object implementing the Operation interface exported from src/components/operations.ts.
• Assign a unique id and provide translation keys for the title, optional success messages, and each step label.
• Register all translation keys in src/i18next.ts to ensure the UI renders text correctly.
• Export the operation and add it to any central collection arrays used by the UI components.

Frequently Asked Questions

What is the Operation interface in iloader?

The Operation interface is a TypeScript contract defined in src/components/operations.ts that standardizes how user-facing actions are structured. It requires an id, titleKey, and steps array, ensuring every operation follows a predictable schema for rendering and execution.

Where do I add translations for new operations?

Add translation entries to the resources object in src/i18next.ts. The keys must match exactly the titleKey, successTitleKey, and step titleKey values defined in your operation object to prevent missing translation warnings at runtime.

Can I add multiple steps to a single operation?

Yes. The steps property accepts an array of OperationStep objects, allowing you to define complex, multi-phase workflows. Each step displays its own label based on its titleKey, and the UI renders them sequentially according to the array order.

How does TypeScript enforce operation definitions?

TypeScript validates your object against the Operation interface at compile time. It enforces required fields like id and steps, type-checks that step objects contain valid properties, and prevents mismatched translation key references, eliminating an entire class of runtime configuration errors.

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