Build Process

Relevant source files

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

• package.json
• vite.config.js
• main.js
• renderer/index.html
• README.md

The Souless project utilizes a combination of Vite as a build tool for the frontend (renderer process) and Electron with Electron Builder to package the application for desktop distribution. This process is managed through a series of NPM scripts, providing separate workflows for development and production builds.

The core architecture separates the game logic, developed with Phaser 3 and bundled by Vite, from the native desktop container provided by Electron. Vite handles fast module replacement during development and optimizes assets for production, while Electron Builder takes the final bundled code and packages it into distributable formats like .exe, .dmg, and .AppImage.

Sources: README.md:3-5, package.json:10-11

Core Technologies

The build and runtime environment is powered by three main technologies defined as dependencies in the project.

Technology	Role	Source
Phaser 3	The game engine used for developing the 2D game logic and rendering.	package.json:30
Vite	A modern build tool that serves the game in a development environment with Hot Module Replacement (HMR) and bundles the game code for production.	package.json:26
Electron	A framework for creating native desktop applications with web technologies (HTML, CSS, JavaScript). It runs the main process and hosts the Vite-built renderer process.	package.json:24
Electron Builder	A tool for packaging and building a ready-for-distribution Electron app for different operating systems.	package.json:25

Sources: package.json:23-31, README.md:31-36

Project Structure

The project is organized to separate the Electron main process logic from the Vite-managed renderer (game) code.

This diagram illustrates the key directories and files involved in the build process.

• main.js: The entry point for the Electron main process.
• src/: Contains all Phaser 3 game source code, including scenes, entities, and systems.
• renderer/: The root directory for the Vite project, containing the main index.html.
• vite.config.js: Configuration file for the Vite build tool, defining aliases, build output, and the dev server.
• dist/: The output directory for the vite build command, containing the bundled and optimized game assets.
• package.json: Defines scripts, dependencies, and the Electron Builder configuration.

Sources: README.md:42-51, vite.config.js:10, vite.config.js:31-33

Development Workflow

The development process is initiated by the yarn dev command, which uses concurrently to run the Vite development server and Electron application in parallel.

"scripts": {
  "dev:vite": "vite",
  "dev:electron": "wait-on http://localhost:5173 && cross-env NODE_ENV=development electron .",
  "dev": "concurrently \"yarn dev:vite\" \"yarn dev:electron\""
}

Sources: package.json:7-9

The wait-on command ensures that the Electron process only starts after the Vite dev server is ready and listening on http://localhost:5173.

The following sequence diagram shows the development startup flow:

In development mode, main.js detects the NODE_ENV=development variable and instructs the BrowserWindow to load its content directly from the Vite development server. This enables features like Hot Module Replacement for rapid iteration.

// main.js
const isDev =
  process.env.NODE_ENV === 'development' ||
  process.defaultApp ||
  /[\\/]electron[\\/]/.test(process.execPath);

// ...

if (isDev) {
  mainWindow.loadURL('http://localhost:5173');
  mainWindow.webContents.openDevTools();
} else {
  mainWindow.loadFile(join(__dirname, 'dist/index.html'));
}

Sources: main.js:9-14, main.js:33-38

Vite Build Configuration

The vite.config.js file defines how the renderer process is bundled.

Key Configuration Options

Option	Value	Description
root	'./renderer'	Specifies the project root for Vite, where index.html is located.
base	'./'	Sets the public base path to a relative path, which is crucial for Electron to locate assets correctly after packaging.
publicDir	'./public'	Defines the directory for static assets that are copied to the output directory as-is.
build.outDir	'../dist'	Sets the output directory for the build to dist/ at the project root.
build.emptyOutDir	true	Ensures the output directory is cleared before each build.
server.port	5173	The port for the Vite development server.

Sources: vite.config.js:10-15, vite.config.js:30-38, vite.config.js:40-45

Path Aliases

Vite is configured with path aliases to simplify import statements within the src directory.

Alias	Path
@	src/
@config	src/config
@scenes	src/scenes
@utils	src/utils
@entities	src/entities
@systems	src/systems
(and others)	(various subdirectories)

Sources: vite.config.js:17-28

Production Build and Packaging

The production build process involves two main steps: bundling the renderer code with Vite and then packaging it with Electron Builder.

NPM Scripts for Production

Script	Command	Description
build	vite build	Bundles the Phaser game code from src/ and renderer/ into the dist/ directory.
start	electron .	Runs the application using the pre-built files in dist/. This is how the packaged app runs.
pack	electron-builder --dir	Packages the application into an unpackaged directory for testing.
dist	electron-builder	Packages the application into distributable installers/archives (e.g., .exe, .dmg).

Sources: package.json:10-13

Production Build Flow

The following diagram illustrates the end-to-end production build process.

Electron Builder Configuration

The build section in package.json contains the configuration for Electron Builder.

"build": {
  "appId": "com.mycompany.mygame",
  "productName": "MyElectronGame",
  "directories": {
    "output": "release"
  },
  "files": [
    "dist/**/*",
    "main.js",
    "preload.js"
  ],
  "win": {
    "target": [ "nsis", "zip" ],
    "icon": "assets/icon.ico"
  },
  "mac": {
    "target": [ "dmg", "zip" ],
    "icon": "assets/icon.icns"
  },
  "linux": {
    "target": [ "AppImage", "deb" ],
    "icon": "assets/icon.png"
  }
}

• directories.output: Specifies that the final packaged files will be placed in the release directory.
• files: Defines which files and directories are included in the final application package. This includes the entire dist directory (the Vite build output) and the Electron main process files.
• win, mac, linux: Platform-specific settings, including the target package formats (e.g., nsis installer for Windows, dmg for macOS) and application icons.

Sources: package.json:32-65

Conclusion

The build process for Souless is a well-defined, two-stage system. Vite provides a modern, fast development experience and optimized production bundles for the Phaser game (renderer process). Electron Builder then takes these bundled assets, combines them with the Electron main process, and packages everything into a cross-platform desktop application. This separation of concerns allows game logic to be developed independently while leveraging Electron's capabilities for desktop integration.