Configuration Guide

Relevant source files

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

• vite.config.ts
• tailwind.config.ts
• electron-builder.json
• tsconfig.json
• package.json
• src/index.css
• components.json
• electron/main.ts
• index.html

The PIXONA application's configuration is managed through a series of dedicated files, each responsible for a specific aspect of the development, build, and packaging process. This guide provides a detailed breakdown of these configuration files, explaining how they work together to create the final desktop application. The core technologies configured include Vite for building the frontend, Electron for the desktop wrapper, Tailwind CSS for styling, and TypeScript for type safety.

Configuration is decentralized, with package.json acting as the central hub for scripts and dependencies, vite.config.ts managing the build and development server, electron-builder.json defining the distributable package, and tailwind.config.ts controlling the application's visual theme. Understanding these files is crucial for customizing the application, managing dependencies, and modifying the build process.

Core Configuration Files

The project's configuration is split across several files. The diagram below shows the main configuration files and their primary roles.

This diagram illustrates the separation of concerns among the key configuration files in the PIXONA project.
Sources: package.json, vite.config.ts, electron-builder.json, tailwind.config.ts, src/index.css, tsconfig.json

package.json: Project Definition and Scripts

This file is the manifest for the project. It defines metadata, lists all dependencies, and contains scripts for development, building, and linting.

Sources: package.json

Dependencies

The project is divided into dependencies required for the production application and devDependencies for the development environment.

• Core Dependencies: react, electron, electron-builder, @tanstack/react-query, react-router-dom.
• UI & Styling: @radix-ui/*, tailwindcss, framer-motion, lucide-react.
• Build & Development: vite, typescript, eslint, concurrently.

Sources: package.json:14-80

Scripts

The scripts section provides commands for common development tasks.

Command	Description
npm run dev	Starts the Vite development server and launches the Electron app with hot-reloading. Uses concurrently to run both processes.
npm run build	Compiles TypeScript, builds the React app using Vite, and then packages it into a distributable installer using electron-builder.
npm run build:win	A convenience script that runs the build process specifically for Windows targets.
npm run lint	Runs ESLint to check the codebase for issues.
npm run preview	Previews the production build locally.

Sources: package.json:6-12

The build script orchestrates a sequence of tasks to create the final application.

This flowchart shows the steps executed by the npm run build command.
Sources: package.json:7

vite.config.ts: Build and Development Server

Vite is used as the build tool for the React frontend. This configuration file defines how the development server runs and how the production assets are bundled.

Sources: vite.config.ts

Key Configurations

• Server: The development server is configured to run on http://localhost:8080.
  Sources: vite.config.ts:9-12
• Plugins:
  • @vitejs/plugin-react-swc: Enables React support with SWC for fast compilation.
  • vite-plugin-electron/simple: Integrates Vite with the Electron main and preload processes, specifying their entry points.
    Sources: vite.config.ts:14-34
• Path Alias: A path alias @{} is configured to resolve to the ./src directory, simplifying import statements.
  Sources: vite.config.ts:36-40
• Build Output: The output directory for the renderer process build is dist, and for Electron-specific files, it is dist-electron.
  Sources: vite.config.ts:19-21, 27-29, 42-45

// vite.config.ts
export default defineConfig(({ mode }) => ({
  // ...
  plugins: [
    react(),
    mode === "development" && componentTagger(),
    electron({
      main: {
        entry: "electron/main.ts",
        // ...
      },
      preload: {
        input: "electron/preload.ts",
        // ...
      },
      renderer: {},
    }),
  ].filter(Boolean),
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  // ...
}));

Sources: vite.config.ts:8-41

electron-builder.json: Application Packaging

This file configures electron-builder to package the application into distributable formats for Windows, macOS, and Linux.

Sources: electron-builder.json

General Configuration

Property	Value	Description
appId	com.pixona.photoapp	The unique application identifier.
productName	PIXONA	The name of the application.
directories.output	release	The folder where installers will be generated.
files	[...]	An array of glob patterns specifying which files to include in the package.
asar	true	Packages the app source code into an ASAR archive for performance and to obscure the source.

Sources: electron-builder.json:3-14

Windows Build (NSIS)

The primary target for Windows is an NSIS installer.

NSIS Option	Value	Description
oneClick	false	Disables one-click installation, allowing for user customization.
allowToChangeInstallationDirectory	true	Lets the user choose where to install the application.
createDesktopShortcut	true	Creates a desktop shortcut.
runAfterFinish	true	Launches the application after installation is complete.

Sources: electron-builder.json:28-38

The configuration also specifies build targets for macOS (dmg, zip) and Linux (AppImage, deb, rpm).
Sources: electron-builder.json:42-65

Styling and Theming

The application's look and feel are managed by Tailwind CSS, with custom themes defined via CSS variables.

tailwind.config.ts

This file configures Tailwind CSS, including content paths, dark mode strategy, and theme extensions.

• Content: Specifies the files that Tailwind should scan for utility classes.
  Sources: tailwind.config.ts:4
• Dark Mode: Uses the class strategy, which relies on a .dark class on the html element.
  Sources: tailwind.config.ts:3
• Theme Extension: Extends the default theme with custom colors, border radiuses, keyframes, and animations. A set of app and sidebar specific colors are defined for consistent theming.
  Sources: tailwind.config.ts:14-131

// tailwind.config.ts
// ...
    extend: {
      colors: {
        // ...
        app: {
          bg: "hsl(var(--app-bg))",
          surface: "hsl(var(--app-surface))",
          hover: "hsl(var(--app-hover))",
          border: "hsl(var(--app-border))",
          text: "hsl(var(--app-text))",
          "text-muted": "hsl(var(--app-text-muted))",
          accent: "hsl(var(--app-accent))",
          "accent-hover": "hsl(var(--app-accent-hover))",
        },
      },
// ...

Sources: tailwind.config.ts:58-68

src/index.css: CSS Variables

This file defines the HSL color values for both light and dark themes as CSS variables. These variables are then consumed by tailwind.config.ts.

/* src/index.css */
@layer base {
  :root {
    --background: 0 0% 4%;
    --foreground: 0 0% 95%;
    /* ... other dark theme variables ... */
    --app-bg: 0 0% 4%;
    --app-surface: 0 0% 6%;
    --app-accent: 211 100% 52%;
  }

  .light {
    --background: 0 0% 100%;
    --foreground: 0 0% 10%;
    /* ... other light theme variables ... */
    --app-bg: 0 0% 98%;
    --app-surface: 0 0% 100%;
    --app-accent: 211 100% 48%;
  }
}

Sources: src/index.css:8-78

The theme can be toggled in the application, as seen in SettingsPage.tsx, which updates the class on the document.documentElement.
Sources: src/pages/SettingsPage.tsx:129-133

tsconfig.json: TypeScript Configuration

This file configures the TypeScript compiler for the entire project. It acts as a solution-style tsconfig.json that references separate configurations for the application code and the Node.js environment (Vite/Electron).

• References: It references tsconfig.app.json (for the React source code) and tsconfig.node.json (for build scripts like vite.config.ts).
  Sources: tsconfig.json:3
• Compiler Options:
  • "baseUrl": ".": Sets the base directory for module resolution.
  • "paths": { "@/*": ["./src/*"] }: Defines the same @/ path alias used in vite.config.ts, ensuring TypeScript can resolve these paths during type-checking.
  • Various strictness flags are relaxed (noImplicitAny, strictNullChecks, etc.) to allow for more flexible coding during development.
    Sources: tsconfig.json:4-14

components.json: UI Library Configuration

This file is specific to the shadcn/ui library and configures how its CLI tool adds new components to the project.

• tailwind.config: Points to tailwind.config.ts.
• tailwind.css: Points to src/index.css.
• aliases: Defines import aliases for components and utilities, consistent with the project's structure.

Sources: components.json:6-16

index.html: Content Security Policy

The main HTML file includes a Content Security Policy (CSP) meta tag, which is a critical security feature for Electron applications. It restricts the sources from which resources (scripts, styles, images) can be loaded, mitigating cross-site scripting (XSS) attacks.

<!-- index.html -->
<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:;" />

This policy allows resources to be loaded from the application's own origin ('self') and includes specific allowances for inline styles/scripts and data URIs, which are common in React development environments.
Sources: index.html:29