Frontend architecture

Whether you are using our EML Template or building your launcher from scratch, the interface is the most important part for your players. It determines how they interact with your server.

This guide defines the recommended architecture, the necessary views to implement, and best practices for connecting your UI to the EML logic.

Architecture guidelines

The Single Page Application (SPA) model

We strongly recommend building your launcher as a Single Page Application. Instead of having multiple HTML files (login.html, home.html) that cause a white flash when switching pages, you should have one single index.html file.

How it works:

All “pages” (login, home, settings) are just <div> containers inside index.html.
You use JavaScript (or CSS) to hide/show these containers to simulate navigation.
Benefit: Instant transitions and a native app feel.

Recommended tech stack

Understanding IPC (Inter-Process Communication)

The two-process model

This is the most critical concept to understand in Electron.

The UI (renderer): This is your HTML/button. It cannot download files or launch Java directly. It is sandboxed for security.
The logic (main): This is where EML Lib runs. It has access to the disk and network.

The flow:

renderer: User clicks “Play”.
renderer: Sends a message (ipcRenderer.send('start-game')) to the main process.
main: Receives the message, runs launcher.launch(), and sends back progress events.
renderer: Listens for progress (ipcRenderer.on('progress')) and updates the progress bar.

Setting up IPC

We recommend the following structure for setting up IPC:

In the main process:
- Create a folder electron/handlers/ to organize your IPC handlers.
- For each feature (auth, launcher, settings), create a separate file (e.g., auth.js, launcher.js, or auth.ts, launcher.ts if using TypeScript).
- In each file, define functions to register IPC handlers using ipcMain.handle or ipcMain.on.
- In electron/main.js, import and call these registration functions.

Create electron/preload.js (or electron/preload.ts if using TypeScript) to expose IPC methods to the renderer using contextBridge.exposeInMainWorld. For example:

import { contextBridge, ipcRenderer } from 'electron'

contextBridge.exposeInMainWorld('api', {
  auth: {
    login: () => ipcRenderer.invoke('auth:login'),
    refresh: () => ipcRenderer.invoke('auth:refresh'),
    logout: () => ipcRenderer.invoke('auth:logout')
  },
  // Other IPC methods...
})

import { contextBridge, ipcRenderer } from 'electron'
import type { IAuthResponse } from './handlers/auth'

contextBridge.exposeInMainWorld('api', {
  auth: {
    login: (): Promise<IAuthResponse> => ipcRenderer.invoke('auth:login'),
    refresh: (): Promise<IAuthResponse> => ipcRenderer.invoke('auth:refresh'),
    logout: (): Promise<{ success: boolean }> => ipcRenderer.invoke('auth:logout')
  },
  // Other IPC methods...
})

Create a wrapper file in the renderer (e.g., src/ipc.js or src/ipc.ts) to provide typed access to these methods. For example:

export const auth = {
  login: async () => await window.api.auth.login(),
  refresh: async () => await window.api.auth.refresh(),
  logout: async () => await window.api.auth.logout()
}

import type { IAuthResponse } from '../electron/handlers/auth'

declare global {
  interface Window {
    api: {
      auth: {
        login: () => Promise<IAuthResponse>
        refresh: () => Promise<IAuthResponse>
        logout: () => Promise<{ success: boolean }>
      }
    }
  }
}

export const auth = {
  login: async () => await window.api.auth.login(),
  logout: async () => await window.api.auth.logout(),
  refresh: async () => await window.api.auth.refresh()
}

In your UI logic files (e.g., src/views/home.js or src/views/home.ts), import and use these IPC methods to interact with EML Lib.

Best practices for code structure

If you are building from scratch, keeping your code organized is vital. Here is a recommended structure for a Vanilla JS/TS project (replace .js with .ts if using TypeScript):

/
├─ package.json
├─ vite.config.js
│
├─ electron/
│  ├─ main.js                     # Main process
│  ├─ preload.js                  # Expose IPC methods to renderer (via ipc.ts)
│  └─ handlers/
│     ├─ auth.js                  # IPC handlers for authentication
│     ├─ launcher.js              # IPC handlers for launcher actions
│     └─ ...                      # Other IPC handlers
│
├─ src/
│  ├─ index.html                  # Single HTML file with all views
│  ├─ app.js                      # Core app logic
│  ├─ init.js                     # Initialize launcher (auto-login, bootstrap, ...)
│  ├─ ipc.ts                      # Expose IPC methods to renderer
│  ├─ state.js                    # State management (switching views, ...)                  
│  ├─ views/
│  │  ├─ login.js                 # Login logic (buttons, forms, ...)
│  │  ├─ home.js                  # Home logic
│  │  └─ ...
│  └─ static/
│     ├─ images/
│     │  ├─ logo.png              # Launcher logo
│     │  └─ ...                   # Other static images
│     └─ styles/
│        ├─ _variables.scss       # Global SCSS variables
│        ├─ main.scss             # Main stylesheet
│        ├─ login.scss            # Login view styles
│        └─ ...                   # Other view styles
│
└─ build/                         # Build assets
   ├─ icon.png
   ├─ icon.icns
   └─ ...

Tip

If using EML Template, this structure is mostly already set up for you. If building from scratch, don’t hesitate to look at EML Template code for inspiration.

Designing the views

Here is the checklist of views (screens) you need to implement to handle all EML features.

Note

Every feature below is documented in later chapters.

This is the entry point.

Home view

This is the main hub where players land after logging in.

Settings view

Allow users to tweak the launcher performance.

Maintenance & Update views

These are “blocking” views. They should overlay everything else when active.

Maintenance: Controlled by EML AdminTool. It should show the reason for maintenance and prevent access to the “Play” button.
Bootstrap Update: When the launcher itself needs an update (managed by the Bootstraps feature), this view should show a spinner or a download bar while the new version is being downloaded.

Development tools

Using DevTools

Since Electron is based on Chromium, you have access to the full Chrome DevTools.

Shortcut: Ctrl + Shift + I (Windows/Linux) or Cmd + Option + I (macOS).
Use the Elements tab to debug your CSS.
Use the Console tab to see logs from the renderer process.

Note

Logs from EML Lib (download progress, auth errors) usually appear in your terminal (where you ran npm run dev), not in the browser console, because they run in the main process. You need to forward them via IPC if you want to see them in the browser console.

Important

The next chapters are API references. To implement the features described there, you need to understand the architecture outlined in this chapter. Do not hesitate to look at EML Template code for examples.

Previous Quick start with EML Lib Next Authentication

Frontend architecture

Architecture guidelines

The Single Page Application (SPA) model

Recommended tech stack

Understanding IPC (Inter-Process Communication)

The two-process model

Setting up IPC

Best practices for code structure

Designing the views

Components

Best practice

Home view

Components

Best practices

Settings view

Components

Best practices

Maintenance & Update views

Development tools

Using DevTools