# Where Is the Main Entry Point for the Motrix Application?

> Discover the main entry point for the Motrix application located in the Electron main-process file src/main/index.ts. Understand its role in orchestrating the bootstrap sequence.

- Repository: [Dr_rOot/Motrix](https://github.com/agalwood/Motrix)
- Tags: internals
- Published: 2026-08-20

---

**The main entry point for Motrix is the Electron main-process file [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts), which compiles to `dist/main/index.cjs` and orchestrates the entire application bootstrap sequence.**

Motrix is a full-featured, open-source download manager built on Electron and React. Understanding the main entry point for the Motrix application is essential for debugging startup behavior, customizing initialization logic, or contributing to the agalwood/Motrix codebase. This entry point controls the main process lifecycle before any renderer window or React UI appears.

## Locating the Entry Point in the Source Code

The path to the entry point spans configuration files that bridge the development source with the production runtime.

### Package.json Declaration

In [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json), the `main` field at lines 15-16 specifies the runtime entry point that Electron executes when the packaged application launches:

```json
"main": "dist/main/index.cjs"

```

This declaration points Electron to the CommonJS bundle generated from the TypeScript source, not the raw source file itself.

### Build Pipeline Configuration

The [`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts) file controls how the source entry point transforms into the executable bundle. According to the build configuration at lines 60-63, Vite explicitly bundles [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts) into `dist/main/index.cjs`:

```typescript
// vite.main.config.ts
build: {
  lib: {
    entry: 'src/main/index.ts',
    formats: ['cjs'],
    fileName: () => 'index.cjs',
  },
  // ...
}

```

When you run the build command, Vite compiles the TypeScript entry point into the CommonJS format that Electron's Node.js environment requires.

## Anatomy of the Main Entry Point (src/main/index.ts)

The file [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts) serves as the logical "main function" of Motrix. It executes synchronously during startup to establish the runtime environment and bootstrap core services.

The entry point performs the following initialization tasks in strict order:

- **Configures logging** by invoking `setupLogger()` to establish the application-wide log directory and verbosity level
- **Creates platform services** via `createElectronPlatformServices()` to resolve user-data directories and detect development mode
- **Initializes core services** including the download engine, task manager, auto-updater, and IPC handlers
- **Manages window lifecycle** through the `WindowManager` class, which instantiates `BrowserWindow` instances

### Bootstrap Sequence Implementation

The entry point follows a specific execution flow to ensure services start in the correct dependency order:

```typescript
// src/main/index.ts – entry point
import { app, BrowserWindow } from 'electron';
import { WindowManager } from './window/window-manager';
import { setupLogger } from './logger';
import { createElectronPlatformServices } from './platform/services';

// Set up logger first
const log = setupLogger({ level: 'info', logDir: '/path/to/logs', isDev: false });

// Create platform services (user data dir, etc.)
const platform = createElectronPlatformServices();

// When Electron is ready, create the main window
app.whenReady().then(() => {
  const winMgr = new WindowManager(platform);
  winMgr.open('main');          // shows the main UI
});

```

This excerpt demonstrates how [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts) initializes infrastructure before calling `app.whenReady()` to display the React-based user interface.

## Running and Debugging the Entry Point

Developers can execute the compiled entry point directly to debug the main process without packaging the entire application.

### Executing the Compiled Entry Point

After building the project, run the compiled main process manually to reproduce the production startup flow:

```bash

# After building the project

node dist/main/index.cjs   # <-- this is the compiled version of src/main/index.ts

```

This command executes the same bootstrap sequence used by the packaged Electron binary, including service initialization and window creation.

### Customizing the Entry Point for Development

To redirect the build to an alternative entry file for experimental builds, modify [`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts):

```typescript
// vite.main.config.ts – change the entry point
export default defineConfig({
  build: {
    lib: {
      entry: 'src/custom/custom-main.ts', // <‑‑ new entry
      formats: ['cjs'],
      fileName: () => 'index.cjs',
    },
    // ...
  },
});

```

Changing the `entry` property redirects the build pipeline to your alternative TypeScript file while maintaining the output structure required by [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json).

## Key Files in the Startup Sequence

These modules interact directly with the main entry point during Motrix initialization:

- **[`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts)** – The core Electron main-process entry that initializes platform services, logging, UI windows, IPC handlers, and the application lifecycle.
- **[`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json)** – Declares the compiled entry point (`dist/main/index.cjs`) at lines 15-16 that Electron executes at runtime.
- **[`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts)** – Vite configuration that bundles [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts) into the final CommonJS file consumed by Electron.
- **[`src/main/window/window-manager.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/window/window-manager.ts)** – Handles creation and management of `BrowserWindow` instances, including the main window instantiation triggered by the entry point.
- **[`src/main/logger.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/logger.ts)** – Provides the `setupLogger()` function invoked immediately when the entry point loads.
- **[`src/main/platform/services.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/platform/services.ts)** – Exports `createElectronPlatformServices()` for platform-specific path resolution and environment detection used early in the startup sequence.

These files form the startup backbone of Motrix, with [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts) acting as the definitive coordinator that orchestrates the transition from process launch to user interface.

## Summary

The main entry point for the Motrix application follows a clear path from TypeScript source to compiled execution:

- **[`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts)** contains the Electron main process logic and service initialization code
- **Vite** compiles this file to `dist/main/index.cjs` as configured in [`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts)
- **[`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json)** directs Electron to load the compiled `dist/main/index.cjs` at runtime
- The entry point establishes logging, platform services, and window management before calling `app.whenReady()`
- Developers can modify [`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts) to specify custom entry points for specialized builds

## Frequently Asked Questions

### What file does Electron load when Motrix starts?

Electron loads `dist/main/index.cjs` as specified in the `main` field of [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json). This compiled file contains the bundled JavaScript code from [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts), which serves as the actual main entry point for the Motrix application.

### How is the TypeScript entry point compiled for production?

The Vite configuration in [`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts) processes [`src/main/index.ts`](https://github.com/agalwood/Motrix/blob/main/src/main/index.ts) and outputs a CommonJS module to `dist/main/index.cjs`. This build step transforms TypeScript into JavaScript, handles module resolution, and prepares the code for Electron's Node.js environment.

### Can I change the main entry point for custom Motrix builds?

Yes. Modify the `entry` property in [`vite.main.config.ts`](https://github.com/agalwood/Motrix/blob/main/vite.main.config.ts) to point to an alternative TypeScript file. Ensure the output `fileName` remains `index.cjs` so that [`package.json`](https://github.com/agalwood/Motrix/blob/main/package.json) can locate the compiled result without modification.

### What happens if src/main/index.ts fails to execute?

If the entry point throws an exception during initialization, the Electron main process crashes before any renderer window opens. Critical failures in `setupLogger()` or `createElectronPlatformServices()` will prevent the application from reaching `app.whenReady()`, resulting in immediate process termination or a blank application window.