Electron has become a popular framework for building cross-platform desktop applications using web technologies like JavaScript, HTML, and CSS. Setting up an Electron project correctly from the start can save time and prevent issues down the line. This article explores best practices for Electron project setup to ensure seamless development and deployment across different operating systems.

Initial Project Setup

Begin by creating a dedicated project directory and initializing a new npm project. Use a clear and descriptive project name to make it easily identifiable.

Run the following commands in your terminal:

mkdir my-electron-app

cd my-electron-app

npm init -y

This creates a package.json file with default settings, which you will customize later.

Installing Essential Dependencies

Install Electron as a development dependency to keep it isolated from production dependencies:

npm install electron --save-dev

Optionally, add other tools like Electron Builder for packaging and cross-platform distribution:

npm install electron-builder --save-dev

Configuring Package.json

Update your package.json to include start scripts and build configurations. Example:

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "build": "electron-builder"
  },
  "devDependencies": {
    "electron": "^latest",
    "electron-builder": "^latest"
  }
}

Project Structure and Main Files

Create a clear directory structure. A typical setup includes:

  • main.js: Entry point for your Electron app.
  • index.html: Main HTML file for the UI.
  • preload.js: Optional script for secure context bridging.
  • assets/: Folder for images and icons.

Ensure your main.js initializes the app and creates the browser window:

const { app, BrowserWindow } = require('electron');

function createWindow() {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  });
  win.loadFile('index.html');
}

app.whenReady().then(createWindow);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

Cross-Platform Compatibility Tips

To ensure your Electron app runs smoothly across Windows, macOS, and Linux, consider the following:

  • Use platform-specific icons for a native look and feel.
  • Handle file paths carefully using path.join() to avoid issues across OSes.
  • Test on all target platforms regularly during development.
  • Configure build scripts to generate platform-specific installers.

Packaging and Distribution

Leverage tools like Electron Builder to package your app into platform-specific installers. Example configuration in package.json:

"build": {
  "appId": "com.example.myapp",
  "productName": "MyElectronApp",
  "files": [
    "main.js",
    "index.html",
    "assets/**/*"
  ],
  "mac": {
    "category": "public.app-category.utilities"
  },
  "win": {
    "target": "nsis"
  },
  "linux": {
    "target": "AppImage"
  }
}

Version Control and Collaboration

Use version control systems like Git to track changes and collaborate effectively. Include a .gitignore file to exclude node_modules and build artifacts.

Sample .gitignore entries:

node_modules/
dist/
build/
.env

Conclusion

Setting up an Electron project with best practices in mind ensures a smoother development process and better cross-platform compatibility. From initial setup to packaging, paying attention to details can significantly improve your application's quality and user experience. Keep testing across platforms and update your setup as Electron evolves to stay current and efficient.