@lakutata/template-electron-react 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# @lakutata/template-electron-react
+
+The Electron template of the [lakutata](https://github.com/lakutata/lakutata) projects with React: the main process is a
+lakutata application serving the actions of its controllers over IPC to the renderer (React, Vite), isolated from Node.js;
+the application is packaged by `lakutata package installer` (electron-builder), for Linux in Docker (`npm run package:linux`).
+
+```bash
+npx @lakutata/cli create --name my-app --template electron-react
+```
+
+The files of the project are in `template/`; `lakutata create` fills `{$APP_NAME}`, `{$APP_ID}`, `{$APP_DESC}`,
+`{$APP_AUTHOR}` and `{$APP_LICENSE}`, and renames `_gitignore` and `_dockerignore`.

package/features/i18n/packages/app/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "i18n:check": "lakutata i18n check --dir src/locales",
+    "i18n:types": "lakutata i18n types --dir src/locales"
+  }
+}

package/features/i18n/packages/app/src/locales/en.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "Hello, {name}!"
+  }
+}

package/features/i18n/packages/app/src/locales/zh-CN.json

@@ -0,0 +1,5 @@
+{
+  "greeting": {
+    "hello": "你好，{name}！"
+  }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@lakutata/template-electron-react",
+  "version": "3.0.0-beta.0",
+  "description": "The Electron template of the lakutata projects with React: the main process is a lakutata application serving the actions of its controllers to the React renderer (Vite) over IPC, packaged by electron-builder.",
+  "keywords": [
+    "lakutata",
+    "lakutata-template"
+  ],
+  "license": "MIT",
+  "files": [
+    "template",
+    "features",
+    "README.md",
+    "LICENSE"
+  ],
+  "lakutata": {
+    "template": "electron-react",
+    "features": {
+      "i18n": "The messages in several languages (lakutata/com/i18n): src/locales, the language of each request"
+    }
+  }
+}

package/template/Dockerfile.installer

@@ -0,0 +1,17 @@
+# The installers of Linux (npm run package:linux), made on Linux by electron-builder: the packages of the configuration
+# (lakutata.installer of packages/app/package.json) in dist/installer. The ones of another architecture: docker buildx
+# build --platform linux/amd64 ... The packages of fpm (deb, rpm) are made by the fpm of the system (the one electron-builder
+# downloads is the one of x64); add the system libraries your native addons need
+FROM node:22-bookworm AS build
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential python3 ruby ruby-dev rpm \
+    && gem install fpm --no-document \
+    && rm -rf /var/lib/apt/lists/*
+ENV USE_SYSTEM_FPM=true
+WORKDIR /project
+COPY . .
+RUN (npm ci --no-audit --no-fund || npm install --no-audit --no-fund) && npm run build && npm run package -w app -- --outdir /installer \
+    && mkdir /packages && find /installer -maxdepth 1 -type f ! -name '*.yml' ! -name '*.blockmap' -exec cp {} /packages \;
+
+FROM scratch
+COPY --from=build /packages /

package/template/README.md

@@ -0,0 +1,73 @@
+# {$APP_NAME}
+
+{$APP_DESC}
+
+A [lakutata](https://github.com/lakutata/lakutata) Electron application. The project is a workspace:
+
+- `packages/app`: the main process, a lakutata application. Its controllers serve their `@ServiceAction` actions to the
+  renderer over IPC (`electronIPCServiceEntrypoint`); `MainWindow` is its window;
+- `packages/ui`: the renderer, React built by Vite. It is isolated from Node.js and from Electron: `window.ipc`
+  (`packages/ui/src/ipc.ts`, through the preload script `packages/app/src/preload.cts`) invokes the actions of the main
+  process, `window.ipc.invoke({cmd: 'greet', name: 'you'})`, and listens to the events it pushes,
+  `window.ipc.on('greeted', listener)` (`once`, `off`);
+- `packages/resources`: the resources of the application, its icon (`logo.png`: the icons of its installers and of its
+  window).
+
+```bash
+npm run dev            # the renderer served by Vite (hot reload) in the window of the application, with its DevTools
+npm test               # the tests of the packages (the actions of the main process, without Electron)
+npm run build          # build the packages, in the order of their dependencies (ui, then app)
+npm start              # start the built application
+npm run package:host      # the installers of this platform: dist/installer (deb, dmg, nsis…)
+npm run package:linux # the ones of Linux, in Docker (Dockerfile.installer): dist/installer
+npm run version:patch  # give the packages their next version
+```
+
+A new action: a method of a controller of `packages/app/src/controllers` decorated by `@ServiceAction({cmd: 'name'}, DTO)`,
+invoked by the renderer with `window.ipc.invoke({cmd: 'name', ...input})`: its input is validated by its DTO, its result is
+given back, its errors are thrown in the renderer (with their `errno`). Each page is a client of the main process: its id
+is the `clientId` of the context of its requests, which the entrypoint pushes events to, `this.entrypoint.notify(clientId,
+'event', ...args)` (the id may be kept to push them later), or to every client, `this.entrypoint.broadcast('event',
+...args)`.
+
+In development (not packaged), the actions are also served over HTTP on the port `DEV_PORT` (9000 by default), for the
+tools such as Postman or curl: `POST /` with `{"cmd": "greet", "name": "you"}` answers the response of the action; the id
+of the client in the `id` header. `GET /events?id=<client>` streams the events pushed to the client (Server-Sent Events):
+
+```bash
+curl -N 'http://localhost:9000/events?id=me' &
+curl -X POST http://localhost:9000/ -H 'id: me' -H 'Content-Type: application/json' -d '{"cmd": "greet", "name": "you"}'
+```
+
+## The packaging
+
+`npm run package:host` builds the packages and makes the installers of the platform it runs on with `lakutata package installer`
+(electron-builder, configured by the `lakutata.installer` of `packages/app/package.json`): the main process bundled with
+its dependencies in the archive of the application, its native addons, the preload script and the built renderer (its
+`lakutata.resources`) next to it, in the resources of Electron. The installers of Windows are made on Windows, the ones of
+macOS on macOS, the ones of Linux on Linux: `npm run package:linux` makes them in Docker on any platform
+(`Dockerfile.installer`, whose system libraries are the ones the native addons need: add yours; `docker buildx build
+--platform linux/amd64` makes the ones of another architecture).
+
+```json
+"installer": {
+  "runtime": "electron",
+  "linux": {"targets": ["deb"], "scripts": {"postinstall": "build/linux/postinstall.sh"}},
+  "mac": {"targets": ["dmg"]},
+  "win": {"targets": ["nsis", "portable"], "scripts": {"postinstall": "build/win/postinstall.ps1"}},
+  "electron": {"linux": {"category": "Utility"}}
+}
+```
+
+`electron` is the configuration of electron-builder (its icons, its file associations, its signature, its updates…),
+merged over the one made from `lakutata.installer`. The scripts of the installers (`scripts`, run by the deb and rpm
+packages, the pkg package of macOS and the installer of NSIS) are the ones of `lakutata package installer` (its documentation in
+`@lakutata/cli`).
+
+The deb packages need the email of their maintainer: the `author` of `packages/app/package.json` is `"Name <email>"` (and
+its `homepage` is the one of the packages).
+
+The native addons built for Node.js (not with N-API) are rebuilt for Electron before packaging: `npx @electron/rebuild`
+(and `npm rebuild` to run the tests with Node.js again).
+
+Electron downloads its binary the first time it runs (`npx install-electron` downloads it ahead, for a CI caching it).

package/template/_dockerignore

@@ -0,0 +1,8 @@
+.git
+node_modules
+**/node_modules
+**/build
+**/dist
+*.log
+.env
+.env.*

package/template/_gitignore

@@ -0,0 +1,13 @@
+node_modules
+build
+*.log
+.env
+.env.*
+.DS_Store
+.idea
+.vscode
+.next
+next-env.d.ts
+.nuxt
+.output
+dist

package/template/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{$APP_ID}",
+  "productName": "{$APP_NAME}",
+  "version": "0.0.1",
+  "description": "{$APP_DESC}",
+  "author": "{$APP_AUTHOR}",
+  "license": "{$APP_LICENSE}",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "lakutata run rebuild",
+    "test": "lakutata run test",
+    "dev": "lakutata run dev --parallel",
+    "start": "npm start -w app",
+    "package:host": "npm run build && npm run package -w app -- --outdir ../../dist/installer",
+    "package:linux": "docker buildx build --file Dockerfile.installer --output type=local,dest=dist/installer .",
+    "version:patch": "lakutata version patch --yes"
+  },
+  "devDependencies": {
+    "@lakutata/builder": "^{$LAKUTATA_VERSION}",
+    "@lakutata/cli": "^{$LAKUTATA_VERSION}",
+    "@types/node": "^22.0.0",
+    "electron": "^44.5.1",
+    "electron-builder": "^26.15.3",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/packages/app/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "app",
+  "productName": "{$APP_NAME}",
+  "version": "0.0.1",
+  "description": "{$APP_DESC}",
+  "author": "{$APP_AUTHOR}",
+  "license": "{$APP_LICENSE}",
+  "private": true,
+  "type": "module",
+  "main": "build/App.js",
+  "scripts": {
+    "clean": "lakutata clean",
+    "build": "tsc",
+    "rebuild": "npm run clean && npm run build",
+    "dev": "npm run rebuild && electron build/App.js --renderer=http://localhost:5173",
+    "start": "electron build/App.js",
+    "test": "node --test \"build/tests/**/*.spec.js\"",
+    "package": "lakutata package installer"
+  },
+  "dependencies": {
+    "lakutata": "^{$LAKUTATA_VERSION}",
+    "ui": "^0.0.1",
+    "resources": "^0.0.1"
+  },
+  "lakutata": {
+    "icon": "../resources/logo.png",
+    "resources": [
+      {
+        "from": "../ui/dist",
+        "to": "renderer"
+      },
+      {
+        "from": "build/preload.cjs",
+        "to": "preload.cjs"
+      },
+      {
+        "from": "../resources/logo.png",
+        "to": "logo.png"
+      }
+    ],
+    "installer": {
+      "runtime": "electron",
+      "name": "{$APP_ID}",
+      "appId": "{$APP_ID}",
+      "linux": {
+        "targets": [
+          "deb"
+        ]
+      },
+      "mac": {
+        "targets": [
+          "dmg"
+        ]
+      },
+      "win": {
+        "targets": [
+          "nsis",
+          "portable"
+        ]
+      },
+      "electron": {
+        "linux": {
+          "category": "Utility",
+          "syncDesktopName": true
+        },
+        "deb": {
+          "depends": [
+            "libgtk-3-0",
+            "libnotify4",
+            "libnss3",
+            "libxss1",
+            "libxtst6",
+            "xdg-utils",
+            "libatspi2.0-0",
+            "libuuid1",
+            "libsecret-1-0",
+            "libasound2"
+          ]
+        }
+      }
+    }
+  }
+}

package/template/packages/app/src/App.ts

@@ -0,0 +1,35 @@
+import {Application, resourcesPath, type ILogger} from 'lakutata'
+import electron from 'electron'
+import path from 'node:path'
+import {fileURLToPath} from 'node:url'
+import {installerConfig} from './config/Config.js'
+
+/**
+ * The directory of the preload script and of the built renderer: the resources of the packaged application
+ * (lakutata.resources), the directory of the main process in development (build/, the renderer of the ui package)
+ */
+const directory: string = resourcesPath() ?? path.dirname(fileURLToPath(import.meta.url))
+
+/**
+ * The URL of the renderer in development (--renderer=<url>, the dev server of Vite)
+ */
+const renderer: string | undefined = process.argv.find((argument: string): boolean => argument.startsWith('--renderer='))?.slice('--renderer='.length)
+
+//One instance of the application: a second one gives its window back to the first one
+if (!electron.app.requestSingleInstanceLock()) {
+    electron.app.exit(0)
+} else {
+    Application
+        .run(installerConfig({
+            directory: directory,
+            renderer: renderer,
+            mode: electron.app.isPackaged ? 'production' : 'development',
+            //The actions served to the tools in development (Postman, curl), not by the packaged application
+            devPort: electron.app.isPackaged ? undefined : Number(process.env.DEV_PORT ?? 9000)
+        }))
+        .onLaunched((app: Application, log: ILogger): void => log.info('%s started in %s mode', app.appName, app.mode()))
+        .onFatalException((error: Error, log: ILogger): void => {
+            log.error('The application cannot start: %s', error.message)
+            electron.app.exit(1)
+        })
+}

package/template/packages/app/src/components/MainWindow.ts

@@ -0,0 +1,110 @@
+import {Application, Component, DTO} from 'lakutata'
+import {Configurable, Inject} from 'lakutata/decorator/di'
+import type {BrowserWindow} from 'electron'
+import {existsSync} from 'node:fs'
+import {createRequire} from 'node:module'
+import path from 'node:path'
+
+/**
+ * The window of the application: the renderer, isolated from Node.js (it invokes the actions of the main process through
+ * the preload script only)
+ */
+export class MainWindow extends Component {
+
+    @Inject(Application)
+    protected readonly app: Application
+
+    @Configurable(DTO.Number().optional().default(1024))
+    protected readonly width: number
+
+    @Configurable(DTO.Number().optional().default(720))
+    protected readonly height: number
+
+    /**
+     * The directory of the preload script and of the built renderer (the resources of the packaged application)
+     */
+    @Configurable(DTO.String().optional())
+    protected readonly directory?: string
+
+    /**
+     * The URL of the renderer in development, the built renderer otherwise
+     */
+    @Configurable(DTO.String().optional())
+    protected readonly renderer?: string
+
+    #window: BrowserWindow | undefined
+
+    /**
+     * The index.html of the built renderer: in the resources of the packaged application, in the ui package otherwise
+     */
+    protected rendererFile(): string {
+        const packaged: string = path.join(this.directory ?? '', 'renderer', 'index.html')
+        if (existsSync(packaged)) return packaged
+        return path.join(path.dirname(createRequire(import.meta.url).resolve('ui/package.json')), 'dist', 'index.html')
+    }
+
+    /**
+     * The icon of the window (Windows, Linux: the windows of macOS show the one of the application): in the resources of
+     * the packaged application, in the resources package otherwise
+     */
+    protected iconFile(): string {
+        const packaged: string = path.join(this.directory ?? '', 'logo.png')
+        if (existsSync(packaged)) return packaged
+        return path.join(path.dirname(createRequire(import.meta.url).resolve('resources/package.json')), 'logo.png')
+    }
+
+    /**
+     * Load the URL of the renderer in development: the dev server of Vite may start after the application
+     * @param window
+     * @param url
+     */
+    protected async loadURL(window: BrowserWindow, url: string): Promise<void> {
+        for (let attempt: number = 1; ; attempt++) {
+            try {
+                return await window.loadURL(url)
+            } catch (error) {
+                if (attempt >= 30 || window.isDestroyed()) throw error
+                await new Promise((resolve: (value: unknown) => void): unknown => setTimeout(resolve, 500))
+            }
+        }
+    }
+
+    protected async init(): Promise<void> {
+        //Electron is loaded with the window: the tests, run by Node.js, serve the actions without it (the package of
+        //Electron downloads its binary when it is loaded)
+        const {app, BrowserWindow} = (await import('electron')).default
+        await app.whenReady()
+        const window: BrowserWindow = new BrowserWindow({
+            width: this.width,
+            height: this.height,
+            title: this.app.appName,
+            icon: this.iconFile(),
+            show: false,
+            webPreferences: {
+                preload: path.join(this.directory ?? '', 'preload.cjs'),
+                contextIsolation: true,
+                nodeIntegration: false,
+                sandbox: true
+            }
+        })
+        this.#window = window
+        window.once('ready-to-show', (): void => window.show())
+        //The application ends with its window
+        window.once('closed', (): void => this.app.exit(0))
+        if (this.renderer) {
+            await this.loadURL(window, this.renderer)
+            window.webContents.openDevTools({mode: 'detach'})
+        } else {
+            await window.loadFile(this.rendererFile())
+        }
+        //A second instance of the application gives its window back
+        app.on('second-instance', (): void => {
+            if (window.isMinimized()) window.restore()
+            window.focus()
+        })
+    }
+
+    protected async destroy(): Promise<void> {
+        if (this.#window && !this.#window.isDestroyed()) this.#window.destroy()
+    }
+}

package/template/packages/app/src/config/Config.ts

@@ -0,0 +1,75 @@
+import type {ApplicationOptions} from 'lakutata'
+import {buildEntrypoints, httpServiceEntrypoint} from 'lakutata/com/entrypoint'
+import {electronIPCServiceEntrypoint, type IPCMain} from 'lakutata/adapter/electron'
+import {MainWindow} from '../components/MainWindow.js'
+import {ExampleController} from '../controllers/ExampleController.js'
+//@if i18n
+import {buildI18nOptions, I18nMiddleware} from 'lakutata/com/i18n'
+import en from '../locales/en.json' with {type: 'json'}
+import zhCN from '../locales/zh-CN.json' with {type: 'json'}
+//@end
+
+export type ConfigOptions = {
+    /**
+     * The directory of the main process, where the preload script and the built renderer are
+     */
+    directory?: string
+    /**
+     * The URL of the renderer in development (the dev server of Vite), the built renderer otherwise
+     */
+    renderer?: string
+    mode?: 'development' | 'production'
+    /**
+     * Open the window, true by default (the tests serve the actions without window)
+     */
+    window?: boolean
+    /**
+     * The ipcMain serving the actions, the one of Electron by default (the tests give theirs)
+     */
+    ipcMain?: IPCMain
+    /**
+     * The port of the HTTP entrypoint of the development, none by default: the actions invoked by the tools (Postman,
+     * curl: POST / with their pattern and their input), the events pushed to them received (GET /events, Server-Sent
+     * Events), the id of their client in the header id (or the query id of the events)
+     */
+    devPort?: number
+}
+
+/**
+ * The options of the application
+ * @param options
+ */
+export function installerConfig(options: ConfigOptions = {}): ApplicationOptions {
+    return {
+        id: '{$APP_ID}',
+        name: '{$APP_NAME}',
+        mode: options.mode ?? 'development',
+        components: {
+            //@if i18n
+            //The messages of the languages (src/locales), bundled with the code; created by the first request
+            i18n: buildI18nOptions({messages: {'en': en, 'zh-CN': zhCN}}),
+            //@end
+            entrypoint: buildEntrypoints({
+                controllers: [ExampleController],
+                //@if i18n
+                //The messages in the language of its environment (LANG)
+                middlewares: [I18nMiddleware],
+                //@end
+                //The renderer invokes the actions over IPC: window.ipc.invoke({cmd: 'greet', name: 'you'})
+                service: [
+                    electronIPCServiceEntrypoint({ipcMain: options.ipcMain}),
+                    ...options.devPort === undefined ? [] : [httpServiceEntrypoint({port: options.devPort})]
+                ]
+            }),
+            ...(options.window === false ? {} : {
+                window: {
+                    class: MainWindow,
+                    directory: options.directory,
+                    renderer: options.renderer
+                }
+            })
+        },
+        //The actions are served before the window loads the renderer
+        bootstrap: options.window === false ? ['entrypoint'] : ['entrypoint', 'window']
+    }
+}

package/template/packages/app/src/controllers/ExampleController.ts

@@ -0,0 +1,41 @@
+import {Controller, Entrypoint, type ServiceContext} from 'lakutata/com/entrypoint'
+import {ServiceAction} from 'lakutata/decorator/ctrl'
+import {Inject} from 'lakutata/decorator/di'
+import {GreetDTO} from '../dtos/GreetDTO.js'
+//@if i18n
+import {Translator} from 'lakutata/com/i18n'
+//@end
+
+export class ExampleController extends Controller {
+
+    /**
+     * Pushes the events to the clients: the windows (window.ipc.on), the tools in development (GET /events)
+     */
+    @Inject('entrypoint')
+    protected readonly entrypoint: Entrypoint
+    //@if i18n
+
+    /**
+     * The messages of the language of the request
+     */
+    @Inject(Translator)
+    protected readonly i18n: Translator
+    //@end
+
+    /**
+     * Invoked by the renderer: window.ipc.invoke({cmd: 'greet', name: 'you'})
+     * @param input
+     */
+    @ServiceAction({cmd: 'greet'}, GreetDTO)
+    public async greet(input: GreetDTO): Promise<{ message: string }> {
+        //An event pushed to the client of the request (window.ipc.on('greeted', listener)), whose id may be kept to push
+        //it events later; this.entrypoint.broadcast pushes one to every client
+        const clientId: string | undefined = (this.context as ServiceContext).clientId
+        if (clientId) this.entrypoint.notify(clientId, 'greeted', input.name)
+        //@if i18n
+        return {message: this.i18n.t('greeting.hello', {name: input.name})}
+        //@else
+        return {message: `Hello, ${input.name}!`}
+        //@end
+    }
+}

package/template/packages/app/src/dtos/GreetDTO.ts

@@ -0,0 +1,7 @@
+import {DTO} from 'lakutata'
+import {Expect} from 'lakutata/decorator/dto'
+
+export class GreetDTO extends DTO {
+    @Expect(DTO.String().required().max(64).description('Who is greeted'))
+    public name: string
+}

package/template/packages/app/src/preload.cts

@@ -0,0 +1,15 @@
+import {contextBridge, ipcRenderer} from 'electron'
+
+/**
+ * The preload script of the window: the transport of window.ipc (packages/ui/src/ipc.ts), the renderer invokes the actions
+ * of the main process and receives the events it pushes, nothing else of Electron or of Node.js
+ */
+contextBridge.exposeInMainWorld('ipcBridge', {
+    //The page is a client of the main process: its id is the clientId of the contexts of its requests
+    invoke: (data: Record<string, unknown>, clientId: string): Promise<unknown> => ipcRenderer.invoke('lakutata:service', data, clientId),
+    //The events of the main process (Entrypoint.notify, broadcast), once the page is subscribed to them
+    subscribe: (clientId: string, listener: (event: string, args: unknown[]) => void): void => {
+        ipcRenderer.on('lakutata:service:event', (_event: unknown, name: string, args: unknown[]): void => listener(name, args))
+        ipcRenderer.send('lakutata:service:subscribe', clientId)
+    }
+})

package/template/packages/app/src/tests/App.spec.ts

@@ -0,0 +1,109 @@
+import {after, before, describe, it} from 'node:test'
+import assert from 'node:assert'
+import {createServer, type Server} from 'node:net'
+import {Application} from 'lakutata'
+import type {IPCMain} from 'lakutata/adapter/electron'
+import {installerConfig} from '../config/Config.js'
+
+/**
+ * The ipcMain of the tests: the actions are invoked as the renderer invokes them, without Electron
+ */
+const handlers: Map<string, (event: unknown, data: unknown) => Promise<unknown>> = new Map()
+const listeners: Map<string, (event: unknown, clientId: string) => void> = new Map()
+const ipcMain: IPCMain = {
+    handle: (channel: string, listener: (event: unknown, data: unknown) => Promise<unknown>): unknown => handlers.set(channel, listener),
+    removeHandler: (channel: string): unknown => handlers.delete(channel),
+    on: (channel: string, listener: (event: unknown, clientId: string) => void): unknown => listeners.set(channel, listener),
+    removeAllListeners: (channel: string): unknown => listeners.delete(channel)
+}
+//The web contents of the renderer: the events pushed to it
+const received: unknown[][] = []
+const sender = {once: (): void => undefined, off: (): void => undefined, send: (...args: unknown[]): unknown => received.push(args)}
+
+/**
+ * Invoke an action as the renderer does (window.ipc.invoke)
+ * @param data
+ */
+function invoke(data: Record<string, unknown>): Promise<any> {
+    return (handlers.get('lakutata:service') as (event: unknown, data: unknown, clientId: string) => Promise<unknown>)({sender: sender}, data, 'page')
+}
+
+/**
+ * A free port, the one of the HTTP entrypoint of the development
+ */
+async function freePort(): Promise<number> {
+    const server: Server = createServer()
+    await new Promise<void>((resolve: () => void): unknown => server.listen(0, '127.0.0.1', resolve))
+    const port: number = (server.address() as { port: number }).port
+    await new Promise<void>((resolve: () => void): unknown => server.close((): void => resolve()))
+    return port
+}
+
+describe('{$APP_NAME}', (): void => {
+
+    let app: Application
+    let devPort: number
+
+    before(async (): Promise<void> => {
+        //@if i18n
+        //The actions answer in the language of the environment: English for the tests
+        process.env.LC_ALL = 'en_US.UTF-8'
+        //@end
+        devPort = await freePort()
+        app = await new Promise<Application>((resolve: (app: Application) => void): void => {
+            Application.run(installerConfig({window: false, ipcMain: ipcMain, devPort: devPort})).onLaunched((launched: Application): void => resolve(launched))
+        })
+    })
+
+    after(async (): Promise<void> => {
+        await app?.dispose()
+    })
+
+    it('serves the actions to the renderer', async (): Promise<void> => {
+        assert.deepStrictEqual(await invoke({cmd: 'greet', name: 'you'}), {success: true, error: null, payload: {message: 'Hello, you!'}})
+    })
+
+    //@if i18n
+    it('serves the actions in the language of the environment', async (): Promise<void> => {
+        process.env.LC_ALL = 'zh_CN.UTF-8'
+        try {
+            assert.deepStrictEqual(await invoke({cmd: 'greet', name: 'you'}), {success: true, error: null, payload: {message: '你好，you！'}})
+        } finally {
+            process.env.LC_ALL = 'en_US.UTF-8'
+        }
+    })
+
+    //@end
+    it('pushes its events to the renderer', async (): Promise<void> => {
+        //The page subscribed to the events
+        listeners.get('lakutata:service:subscribe')!({sender: sender}, 'page')
+        received.length = 0
+        await invoke({cmd: 'greet', name: 'you'})
+        assert.deepStrictEqual(received, [['lakutata:service:event', 'greeted', ['you']]])
+    })
+
+    it('serves the actions and their events to the tools of the development over HTTP', async (): Promise<void> => {
+        //The events of the client (Server-Sent Events): its id first
+        const events: Response = await fetch(`http://127.0.0.1:${devPort}/events?id=tool`)
+        const reader = events.body!.getReader()
+        let received: string = ''
+        const until = async (pattern: RegExp): Promise<void> => {
+            while (!pattern.test(received)) received += new TextDecoder().decode((await reader.read()).value)
+        }
+        await until(/event: client/)
+        const response: Response = await fetch(`http://127.0.0.1:${devPort}/`, {method: 'POST', headers: {'Content-Type': 'application/json', 'id': 'tool'}, body: JSON.stringify({cmd: 'greet', name: 'you'})})
+        assert.deepStrictEqual(await response.json(), {success: true, error: null, payload: {message: 'Hello, you!'}})
+        await until(/event: greeted\ndata: \["you"\]/)
+        await reader.cancel()
+    })
+
+    it('refuses an invalid input', async (): Promise<void> => {
+        const response = await invoke({cmd: 'greet'})
+        assert.strictEqual(response.success, false)
+        assert.match(response.error.message, /name/)
+    })
+
+    it('refuses an unknown action', async (): Promise<void> => {
+        assert.strictEqual((await invoke({cmd: 'unknown'})).success, false)
+    })
+})

package/template/packages/app/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "lakutata/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "build",
+    "sourceMap": true
+  },
+  "include": ["src"]
+}

package/template/packages/resources/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "resources",
+  "version": "0.0.1",
+  "private": true,
+  "description": "The resources of the application: its icon (logo.png, lakutata.icon of the app package), made into the icons of each platform"
+}

package/template/packages/ui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'" />
+    <title>{$APP_NAME}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/packages/ui/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "ui",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "clean": "lakutata clean dist",
+    "build": "vite build",
+    "rebuild": "npm run clean && npm run build",
+    "dev": "vite --port 5173 --strictPort",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "vite": "^8.3.1"
+  }
+}

package/template/packages/ui/src/App.tsx

@@ -0,0 +1,26 @@
+import {useEffect, useState} from 'react'
+
+export function App() {
+    const [message, setMessage] = useState<string>('…')
+    const [pushed, setPushed] = useState<string>('')
+
+    useEffect((): () => void => {
+        //An event the main process pushes
+        const greeted = (name: string): void => setPushed(`Pushed by the main process: ${name}`)
+        window.ipc.on('greeted', greeted)
+        window.ipc.invoke<{ message: string }>({cmd: 'greet', name: '{$APP_NAME}'})
+            .then((result: { message: string }): void => setMessage(result.message))
+            .catch((error: Error): void => setMessage(error.message))
+        return (): void => {
+            window.ipc.off('greeted', greeted)
+        }
+    }, [])
+
+    return (
+        <main>
+            <h1>{$APP_NAME}</h1>
+            <p>{message}</p>
+            <p>{pushed}</p>
+        </main>
+    )
+}

package/template/packages/ui/src/ipc.ts

@@ -0,0 +1,125 @@
+/**
+ * The response of an action of the main process
+ */
+type ServiceResponse<T> = {
+    success: boolean
+    error: { message?: string, errno?: string } | null
+    payload: T
+}
+
+/**
+ * A listener of an event of the main process, given its arguments
+ */
+type Listener = (...args: any[]) => void
+
+declare global {
+    interface Window {
+        /**
+         * The transport of the IPC, given by the preload script of the window of the application
+         */
+        ipcBridge?: {
+            invoke<T>(data: Record<string, unknown>, clientId: string): Promise<ServiceResponse<T>>
+            subscribe(clientId: string, listener: (event: string, args: unknown[]) => void): void
+        }
+        /**
+         * The IPC of the main process
+         */
+        ipc: IPC
+    }
+}
+
+/**
+ * The IPC of the main process (window.ipc): its actions invoked, their results given and their errors thrown (with their
+ * errno), its events listened to. Defined in the page: the errors and the listeners given across the preload script lose
+ * their properties and their identity
+ */
+export class IPC {
+
+    /**
+     * The id of the page, a client of the main process (the clientId of the contexts of its requests, which the events
+     * are pushed to): a new one each time the page is loaded
+     */
+    public readonly id: string = crypto.randomUUID()
+
+    readonly #listeners: Map<string, Listener[]> = new Map()
+
+    constructor() {
+        window.ipcBridge?.subscribe(this.id, (event: string, args: unknown[]): void => {
+            for (const listener of [...this.#listeners.get(event) ?? []]) listener(...args)
+        })
+    }
+
+    /**
+     * Invoke an action of the main process (a @ServiceAction of its controllers): window.ipc.invoke({cmd: 'greet', name: 'you'})
+     * @param data its pattern and its input
+     */
+    public async invoke<T = any>(data: Record<string, unknown>): Promise<T> {
+        if (!window.ipcBridge) throw new Error('The actions are invoked in the window of the application (npm run dev)')
+        const response: ServiceResponse<T> = await window.ipcBridge.invoke<T>(data, this.id)
+        if (!response.success) throw Object.assign(new Error(response.error?.message ?? 'The action failed'), response.error)
+        return response.payload
+    }
+
+    /**
+     * Listen to an event of the main process
+     * @param event
+     * @param listener
+     */
+    public on(event: string, listener: Listener): this {
+        this.#listeners.set(event, [...this.#listeners.get(event) ?? [], listener])
+        return this
+    }
+
+    /**
+     * Listen to the next event of the main process
+     * @param event
+     * @param listener
+     */
+    public once(event: string, listener: Listener): this {
+        const once: Listener & { listener?: Listener } = (...args: any[]): void => {
+            this.off(event, once)
+            listener(...args)
+        }
+        once.listener = listener
+        return this.on(event, once)
+    }
+
+    /**
+     * Stop listening to an event of the main process
+     * @param event
+     * @param listener
+     */
+    public off(event: string, listener: Listener): this {
+        this.#listeners.set(event, (this.#listeners.get(event) ?? []).filter((existing: Listener & { listener?: Listener }): boolean => existing !== listener && existing.listener !== listener))
+        return this
+    }
+
+    /**
+     * Stop listening to an event of the main process (off)
+     * @param event
+     * @param listener
+     */
+    public removeListener(event: string, listener: Listener): this {
+        return this.off(event, listener)
+    }
+
+    /**
+     * Stop listening to an event of the main process, or to every event
+     * @param event
+     */
+    public removeAllListeners(event?: string): this {
+        if (event === undefined) this.#listeners.clear()
+        else this.#listeners.delete(event)
+        return this
+    }
+
+    /**
+     * Kept for the renderers of the version 2 (the listeners of an event are not limited)
+     * @param _count
+     */
+    public setMaxListeners(_count: number): this {
+        return this
+    }
+}
+
+window.ipc = new IPC()

package/template/packages/ui/src/main.tsx

@@ -0,0 +1,11 @@
+//window.ipc, before the components using it
+import './ipc'
+import {StrictMode} from 'react'
+import {createRoot} from 'react-dom/client'
+import {App} from './App'
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App/>
+    </StrictMode>
+)

package/template/packages/ui/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template/packages/ui/vite.config.ts

@@ -0,0 +1,8 @@
+import {defineConfig} from 'vite'
+import react from '@vitejs/plugin-react'
+
+//The pages are loaded from the files of the packaged application: their paths are relative
+export default defineConfig({
+    base: './',
+    plugins: [react()]
+})