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

> Learn how to define a new operation type in iloader. Implement the Operation interface, specify IDs and steps, and register translations for a seamless developer experience.

- Repository: [Nicholas Sharp/iloader](https://github.com/nab138/iloader)
- Tags: how-to-guide
- Published: 2026-09-12

---

**To define a new operation type in iloader, implement the `Operation` interface in [`src/components/operations.ts`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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.

```typescript
// 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,
];

```

```typescript
// 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`](https://github.com/nab138/iloader/blob/main/src/components/operations.ts)**: Declares the `Operation` and `OperationStep` interfaces and houses the built-in operation constants.
- **[`src/i18next.ts`](https://github.com/nab138/iloader/blob/main/src/i18next.ts)**: Contains the i18next translation resources referenced by `titleKey` and other localization keys.
- **[`src/update.ts`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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`](https://github.com/nab138/iloader/blob/main/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.