Getting Started

Relevant source files

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

• README.md
• package.json
• electron-builder.json
• electron/main.ts
• vite.config.ts
• index.html
• src/App.tsx

This guide provides a comprehensive overview for setting up, developing, and building the PIXONA desktop photo management application. PIXONA is a Windows application inspired by Apple Photos, built using Electron, React, and TypeScript. It offers features like multi-drive photo scanning, a modern dark UI, and various organization tools.

This document covers the necessary prerequisites, installation of dependencies, running the application in a development environment, and packaging it for production. It is intended for developers looking to contribute to the project or understand its core setup and build processes.

Sources: README.md:3-8, README.md:63-68, package.json:2-5

## Architecture Overview

PIXONA is an Electron application that consists of three main parts: the Main process, the Preload script, and the Renderer process (a React application).

• Main Process (electron/main.ts): Handles window creation, application lifecycle events, and native OS integrations like file system access. It exposes functionalities to the Renderer process via Inter-Process Communication (IPC).
• Preload Script (electron/preload.ts): A secure bridge that exposes specific IPC channels from the Main process to the Renderer process through the window.electron API.
• Renderer Process (src/): The user interface, built with React, TypeScript, and Tailwind CSS. It runs in a browser window and communicates with the Main process via the Preload script to perform backend tasks.

Sources: README.md:63-70, electron/main.ts, electron/preload.ts

The following diagram illustrates the high-level architecture of the application.

## Prerequisites

Before setting up the project, ensure the following software is installed on your system:

• Node.js: Version 18.x or higher.
• npm: Version 9.x or higher (comes with Node.js).
• Git: Optional, for cloning the repository.

You can verify the versions using the following commands:

node --version
npm --version

Sources: README.md:32-40

## Installation

To get the project running locally, follow these steps:

1. Clone the Repository:

   git clone <your-repo-url>
   cd pixona
   

2. Install Dependencies:
   This command installs all the required packages defined in package.json, including React, Electron, and Vite.

   npm install
   

Sources: README.md:44-58, package.json:8-10

## Development

To run the application in development mode with hot-reloading, use the following script.

npm run dev

Sources: package.json:7, README.md:63-65

This command, defined in package.json, performs two concurrent actions:

1. Starts the Vite development server for the React frontend, typically on http://localhost:8080.
2. Waits for the Vite server to be ready, then launches the Electron application window, which loads the content from the Vite server.

Sources: package.json:7, vite.config.ts:9-12, README.md:67-73

The development workflow is illustrated below:

### Project Structure

The project is organized into several key directories:

Directory	Description	Source
electron/	Contains the Electron main process (main.ts) and preload script (preload.ts).	README.md:64
src/	The source code for the React frontend application, including components, pages, and styles.	README.md:71
public/	Static assets like icons that are copied to the build output.	README.md:86
release/	The output directory for production builds, containing the installer.	electron-builder.json:6

Sources: README.md:63-89, electron-builder.json:6

### Content Security Policy

For security, a Content Security Policy (CSP) is defined in the main HTML file. This policy restricts the sources from which content (like scripts, styles, and images) can be loaded, helping to mitigate cross-site scripting (XSS) attacks.

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: file: https:; media-src 'self' blob: file:; font-src 'self' data:; connect-src 'self' https: wss:;" />

Sources: index.html:28-28

## Building for Production

To create a production-ready Windows installer, run the build script.

npm run build

Sources: package.json:8, README.md:124-126

This script executes a sequence of tasks to compile, bundle, and package the application.

The build process is visualized in the diagram below:

### Build Configuration

The build process is configured in electron-builder.json. This file specifies the application ID, product name, output directories, and platform-specific targets. For Windows, it is configured to create an NSIS installer.

Key configuration properties include:

• appId: com.pixona.photoapp
• productName: PIXONA
• directories.output: release
• win.target: nsis (for the installer) and portable

Sources: electron-builder.json:3-7, electron-builder.json:15-22

Here is a snippet from the NSIS configuration:

"nsis": {
  "oneClick": false,
  "perMachine": false,
  "allowToChangeInstallationDirectory": true,
  "createDesktopShortcut": true,
  "createStartMenuShortcut": true,
  "shortcutName": "PIXONA"
}

This configuration creates a standard installer that allows the user to choose the installation directory and creates desktop and start menu shortcuts.

Sources: electron-builder.json:28-36

## Available Scripts

The package.json file defines several scripts for common development tasks.

Command	Description	Source
npm run dev	Starts the application in development mode with hot-reloading.	package.json:7
npm run build	Compiles the app and creates a production installer for the host OS.	package.json:8
npm run build:win	Builds the application specifically for Windows.	package.json:9
npm run preview	Previews the production build locally without a full install.	package.json:14
npm run lint	Runs ESLint to check the codebase for issues.	package.json:13

Sources: package.json:6-15, README.md:150-155