Development and Build Process

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• vite.config.ts
• electron-builder.json
• README.md
• electron/main.ts

This document provides a technical overview of the development and build process for the PIXONA desktop application. The project is built using React and TypeScript for the frontend, with Electron used to package it as a native desktop application. Vite serves as the build tool for both development and production, providing a fast and modern development experience.

The process is managed through a set of npm scripts, which handle everything from starting a local development server with hot-reloading to packaging the application into distributable installers for Windows, macOS, and Linux. Configuration for these processes is defined in vite.config.ts for the development server and electron-builder.json for the production build.

Sources: README.md:3-5, package.json, vite.config.ts, electron-builder.json

Prerequisites

To begin development, the following tools must be installed on the local machine:

• Node.js: v18.x or higher
• npm: v9.x or higher

After cloning the repository, all project dependencies can be installed by running npm install.

Sources: README.md:30-46

Project Structure

The repository is organized to separate the Electron main process code from the React renderer (UI) code. This separation is crucial for managing the application's logic and build configurations.

pixona/
├── electron/              # Electron main process files
│   ├── main.ts           # Main Electron process (IPC handlers, window management)
│   ├── preload.ts        # Preload script (secure IPC bridge)
│   └── tsconfig.json     # TypeScript config for Electron
├── src/                  # React application source (renderer process)
│   ├── components/       # Reusable UI components
│   ├── pages/            # Main app pages/views
│   └── App.tsx           # Main app component
├── public/               # Static assets
├── electron-builder.json # Electron build configuration
├── vite.config.ts        # Vite & Electron plugin config
├── tailwind.config.ts    # Tailwind CSS configuration
└── package.json          # Dependencies and scripts

Sources: README.md:65-88

Key Dependencies

The project relies on several key libraries for its functionality, development, and build processes.

Category	Library	Description
UI Framework	react	The core library for building the user interface.
Desktop Framework	electron	Enables the web application to run as a native desktop application.
Build Tool	vite	A fast frontend build tool for development and bundling.
Packaging	electron-builder	Packages the Electron app into distributable installers.
Vite-Electron Bridge	vite-plugin-electron	Integrates Vite with Electron for a seamless development workflow.
Development	concurrently	Runs multiple commands (Vite and Electron) simultaneously.
Development	wait-on	Waits for the Vite dev server to be ready before launching Electron.
Language	typescript	Provides static typing for JavaScript.

Sources: package.json:13-83

NPM Scripts

The core development and build workflows are managed by scripts defined in package.json.

Command	Description
npm run dev	Starts the application in development mode. It runs the Vite dev server and the Electron app concurrently, with hot-reloading enabled.
npm run build	Compiles the TypeScript code, builds the React app using Vite, and then packages the application into a production-ready installer using electron-builder.
npm run preview	Previews the production build locally.
npm run lint	Runs ESLint to check the codebase for issues.

Sources: package.json:6-12, README.md:214-221

Development Process

The development process is initiated by running npm run dev. This command leverages concurrently to execute two main tasks in parallel: starting the Vite development server and launching the Electron application.

"scripts": {
  "dev": "concurrently \"vite\" \"wait-on http://localhost:5173 && electron .\"",
  ...
}

Sources: package.json:7

The wait-on command ensures that the Electron process only starts after the Vite server is running and accessible at http://localhost:5173 (or http://localhost:8080 as configured in vite.config.ts).

The following diagram illustrates the development startup flow.

This diagram shows how npm run dev orchestrates the startup of both the Vite server and the Electron application.
Sources: package.json:7, vite.config.ts:10, electron/main.ts:46-48

Vite Configuration

The vite.config.ts file is central to the development process. It uses vite-plugin-electron to bridge Vite with Electron.

// vite.config.ts
export default defineConfig(({ mode }) => ({
  server: {
    host: "::",
    port: 8080,
  },
  plugins: [
    // ...
    electron({
      main: {
        entry: "electron/main.ts",
        // ...
      },
      preload: {
        input: "electron/preload.ts",
        // ...
      },
      renderer: {},
    }),
  ],
  // ...
}));

This configuration tells Vite to:

1. Run the development server on port 8080.
2. Use electron/main.ts as the entry point for the Electron main process.
3. Use electron/preload.ts as the preload script.

Sources: vite.config.ts:8-29

Electron Main Process in Development

In electron/main.ts, a check for the development environment (isDev) determines how the application window loads its content. In development, it loads the URL from the Vite server, which enables hot-reloading. For production, it loads the static index.html file from the build output.

// electron/main.ts
const isDev = process.env.NODE_ENV === 'development' || !app.isPackaged;

// ...

// Load the app
if (isDev) {
  mainWindow.loadURL('http://localhost:8080');
} else {
  mainWindow.loadFile(path.join(__dirname, '../dist/index.html'));
}

Sources: electron/main.ts:12, electron/main.ts:46-50

Build Process

The production build is created by running npm run build. This script chains three commands: tsc, vite build, and electron-builder.

The following diagram shows the production build flow.

This diagram illustrates the steps from type-checking to final package creation for multiple platforms.
Sources: package.json:8, electron-builder.json:8

Build Configuration (electron-builder.json)

The electron-builder.json file defines how the application is packaged for distribution. It specifies the application ID, product name, output directories, and platform-specific targets.

Key configuration options are summarized below:

Property	Value	Description
appId	com.pixona.photoapp	The unique application identifier.
productName	PIXONA	The name of the application displayed to the user.
directories.output	release	The directory where the final installers will be created.
files	["dist/**/*", "dist-electron/**/*", ...]	Specifies which files and directories to include in the package.
win.target	nsis, portable	Defines the Windows build targets: a standard NSIS installer and a portable executable.
mac.target	dmg, zip	Defines the macOS build targets.
linux.target	AppImage, deb, rpm	Defines the Linux build targets.
nsis.allowToChangeInstallationDirectory	true	Allows the user to choose the installation path during setup on Windows.

Sources: electron-builder.json:3-56

The build process results in platform-specific installers and packages being placed in the release/ directory, ready for distribution.

Sources: electron-builder.json:8, README.md:195-200