> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxhub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Module API reference

> Reference guide for the LynxHub module APIs.

LynxHub modules (or cards) represent standalone AI applications or tools. Each module integrates with the host by exporting backend methods and configuring renderer behaviors.

Unlike extensions, modules are purely configuration and API calling wrappers. The host application handles all user interface rendering, layouts, themes, and global state tracking.

***

## Entry points

A module must provide main process logic and renderer process configuration.

### Backend entry point

Your backend main script must export a default function that initializes your modules.

```typescript theme={null}
import {MainModules, MainModuleUtils} from '../../src/common/types/plugins/modules';

export default async function initialModule(utils: MainModuleUtils): Promise<MainModules[]>;
```

This function returns an array of `MainModules` objects mapping each module ID to its main process methods.

```typescript theme={null}
export type MainModules = {
  id: string;
  methods: () => CardMainMethods;
};
```

### Frontend entry point

Your frontend renderer script must export the `CardModules` configuration list as its default export.

```typescript theme={null}
import {CardModules} from '../../src/common/types/plugins/modules';

const rendererModules: CardModules = [
  // ... your PagesData pages
];

export default rendererModules;
```

***

## Backend API reference

The backend entry point receives the `utils` helper object. Use it to access directories, manage processes, and handle persistent storage.

### MainModuleUtils

Use this object to interact with the host backend environment.

#### `storage`

Simple key-value database storage helper.

* `get<T>(key: string): T` - Retrieves custom data synchronously.
* `set<T>(key: string, data: T): void` - Saves custom data.

#### `ipc`

IPC communications helper.

* `handle(channel: string, listener: (event: any, ...args: any[]) => any): void` - Registers an IPC invocation handler.
* `on(channel: string, listener: (event: any, ...args: any[]) => void): void` - Listens to IPC messages.
* `send(channel: string, ...args: any[]): void` - Emits an IPC message to the renderer.

#### `pty`

Exposes the `node-pty` module. Use it to spawn pseudo-terminals for running interactive CLI workflows.

#### `isPullAvailable(dir: string): Promise<boolean>`

Checks if Git pull is available in the target directory.

#### `trashDir(dir: string): Promise<void>`

Moves the specified directory to the system trash.

#### `removeDir(dir: string): Promise<void>`

Deletes the specified directory permanently.

#### `getInstallDir(id: string): string | undefined`

Returns the absolute installation directory for the card module.

#### `getConfigDir(): string | undefined`

Returns the user data configuration directory for LynxHub.

#### `pullDir(dir: string, showTaskbarProgress?: boolean): Promise<void>`

Performs a Git pull operation in the specified directory.

#### `getExtensions_TerminalPreCommands(id: string): string[]`

Retrieves pre-launch commands defined by extensions for the specified card.

### CardMainMethods

These are the backend methods you implement for your card modules.

#### `getRunCommands(): Promise<string | string[]>`

**Required**. Returns the CLI commands needed to launch the module's server or process.

#### `readArgs(): Promise<ChosenArgument[]>`

*Optional*. Reads saved launch arguments from a configuration file.

#### `saveArgs(args: ChosenArgument[]): Promise<void>`

*Optional*. Saves launch arguments chosen by the user.

#### `mainIpc(): void`

*Optional*. Sets up backend IPC handlers. Executed during module initialization.

#### `updateAvailable(): Promise<boolean>`

*Optional*. Returns whether an update is available for this module.

#### `isInstalled(): Promise<boolean>`

*Optional*. Returns whether the module is currently installed.

#### `uninstall(): Promise<void>`

*Optional*. Clears folders and files when the user uninstalls the card.

***

## Frontend API reference

The frontend configuration defines pages, cards, metadata, and custom installation/updater wizards.

### CardRendererMethods

These methods define renderer behaviors for your card module.

#### `catchAddress(line: string): string | undefined`

*Optional*. Inspects each terminal output line during startup. Returns the URL of the running web interface once detected (e.g., `http://127.0.0.1:7860`).

#### `fetchExtensionList(): Promise<ExtensionData[]>`

*Optional*. Fetches a list of extensions available for the card.

#### `parseArgsToString(args: ChosenArgument[]): string`

*Optional*. Serializes the arguments array into a single CLI parameters string.

#### `parseStringToArgs(args: string): ChosenArgument[]`

*Optional*. Parses a CLI string back into an arguments array.

#### `cardInfo(api: CardInfoApi, callback: CardInfoCallback): void`

*Optional*. Populates details inside the card information modal.

##### `CardInfoApi`

* `installationFolder?: string` - Absolute installation path of the card.
* `storage`: `{ get: <T = any>(key: string) => Promise<T>; set: <T = any>(key: string, data: T) => void }` - Asynchronous storage get/set interface.
* `ipc`: `RendererIpcTypes` - Inter-process communication handler.
* `getFolderSize(dir: string): Promise<number>` - Queries absolute size on disk of the folder.
* `getFolderCreationTime(dir: string): Promise<string>` - Queries folder creation date.
* `getLastPulledDate(dir: string): Promise<string>` - Queries last Git pull execution date.
* `getCurrentReleaseTag(dir: string): Promise<string>` - Queries current active Git release tag.

##### `CardInfoCallback`

* `setDescription(descriptions: CardInfoDescriptions): void` - Pushes custom list sections of name-result labels to render in the card modal.
* `setOpenFolders(dir: string[] | undefined): void` - Pushes a list of folder paths to be displayed as clickable buttons that open in the native explorer.

#### `manager`

*Optional*. Defines the installation and update workflows:

* `startInstall(stepper: InstallationStepper): void` - Triggers the installation wizard.
* `updater` - Defines updates:
  * `updateType: 'git' | 'stepper'` - Git-based pull or stepper-based update workflow.
  * `startUpdate(stepper: InstallationStepper, dir?: string): void` - Triggers the updater wizard.

### InstallationStepper

The installation stepper manages the setup UI wizard.

#### `initialSteps(stepTitles: InitialSteps): void`

Registers the list of steps to display on the progress timeline.

##### `InitialSteps`

```typescript theme={null}
type InitialSteps = InitialStep[];

type InitialStep =
  | string
  | {
      title: string;
      alerts: CustomAlertParams[];
    };

type CustomAlertParams = {
  type?: 'default' | 'note' | 'warning' | 'danger';
  title: string;
  description?: string;
  urls?: {title: string; url: string}[];
};
```

#### `nextStep(): Promise<void>`

Advances the installer to the next step.

#### `starterStep(options?: StarterStepOptions): Promise<InstallationMethod>`

Displays the initial installer step. Resolves to the user's choice: install clean or locate an existing folder.

##### `StarterStepOptions`

```typescript theme={null}
type StarterStepOptions = {
  disableSelectDir?: boolean;
};
```

##### `InstallationMethod`

```typescript theme={null}
type InstallationMethod = {
  chosen: 'install' | 'locate';
  targetDirectory?: string;
};
```

#### `cloneRepository(url: string): Promise<string>`

Clones a Git repository to the target directory. Returns the path of the cloned repository.

#### `runTerminalScript(workingDirectory: string, scriptFileName: string): Promise<void>`

Executes a terminal script file. Resolves when the script finishes and the user clicks **Next**.

#### `executeTerminalCommands(commands: string | string[], workingDirectory?: string): Promise<void>`

Executes commands in the specified directory. Resolves when execution completes.

#### `downloadFileFromUrl(fileUrl: string): Promise<string>`

Downloads a file to the user's downloads folder. Returns the downloaded file's path.

#### `progressBar(isIndeterminate: boolean, title?: string, percentage?: number, description?: { label: string, value: string }[]): void`

Configures a progress bar overlay. Use this to represent custom tasks.

#### `setInstalled(dir?: string): void`

Saves the target installation directory and flags the module as installed.

#### `setUpdated(): void`

Flags the module as updated.

#### `collectUserInput(inputFields: UserInputField[], title?: string): Promise<UserInputResult[]>`

Displays a dialog requesting user inputs (checkboxes, text inputs, selectors). Resolves with the inputs.

##### `UserInputField`

```typescript theme={null}
type UserInputField = {
  id: string;
  label: string;
  type: 'checkbox' | 'text-input' | 'select' | 'directory' | 'file';
  selectOptions?: string[];
  defaultValue?: string | boolean;
  isRequired?: boolean;
};
```

##### `UserInputResult`

```typescript theme={null}
type UserInputResult = {
  id: string;
  result: string | boolean;
};
```

#### `showFinalStep(resultType: 'success' | 'error', resultTitle: string, resultDescription?: string): void`

Displays the final completion step of the installer wizard.

#### `ipc`

IPC communications helper.

* `invoke<T>(channel: string, ...args: any[]): Promise<T>` - Invokes a backend handler.
* `on(channel: string, listener: (event: any, ...args: any[]) => void): () => void` - Registers a listener. Returns a cleanup unsubscribe function.
* `send(channel: string, ...args: any[]): void` - Sends an IPC message.

#### `storage`

* `get<T>(key: string): Promise<T>` - Retrieves stored data asynchronously.
* `set<T>(key: string, data: T): void` - Saves stored data.

#### `postInstall`

Post-installation automated tasks.

* `installExtensions(extensionURLs: string[], extensionsDir: string): Promise<void>` - Downloads a set of Git extensions for the module.
* `config(configs: ModuleConfigOptions): void` - Automatically configures auto-updates, custom arguments presets, and pre-launch hooks.

##### `ModuleConfigOptions`

```typescript theme={null}
type ModuleConfigOptions = {
  /** If true, automatically updates all extensions when launching WebUI */
  autoUpdateExtensions?: boolean;
  /** If true, automatically updates the WebUI itself */
  autoUpdateCard?: boolean;
  /** Pre-defined arguments to pass to the WebUI */
  customArguments?: {
    /** Name of the preset configuration */
    presetName: string;
    /** Array of custom arguments */
    customArguments: {
      /** Name of the argument like --use-cpu */
      name: string;
      /** Value of the argument (set empty string '' if it is a boolean or checkbox) */
      value: string;
    }[];
  };
  /** Custom commands to execute instead of the actual command to launch WebUI */
  customCommands?: string[];
  /** Defines the behavior of the browser and terminal when launching */
  launchBehavior?: Omit<CustomRunBehaviorData, 'cardID'>;
  /** Actions to perform before launching WebUI */
  preLaunch?: {
    /** Commands to execute before launch */
    preCommands: string[];
    /** Paths to open before launch */
    openPath: {path: string; type: 'folder' | 'file'}[];
  };
};
```

#### `utils`

Helper operations that do not affect the wizard UI.

* `decompressFile(compressedFilePath: string): Promise<string>`
* `validateGitRepository(localDirectory: string, repositoryUrl: string): Promise<boolean>`
* `verifyFilesExist(directory: string, itemNames: string[]): Promise<boolean>`
* `openFileOrFolder(itemPath: string): void`

#### `topToast(message: string): void`

Displays a toast at the top of the window.

#### `bottomToast(message: string): void`

Displays a toast at the bottom of the window.