Créer un gestionnaire de fichiers de bureau avec Electron
Créez un gestionnaire de fichiers Electron sécurisé avec un moteur de rendu isolé, un pont IPC preload et des gestionnaires main pour parcourir, ouvrir, renommer et mettre des fichiers à la corbeille.
Un gestionnaire de fichiers Electron répartit le travail entre trois processus. Le processus principal (main) exécute toutes les opérations sur le système de fichiers et le shell. Le script de préchargement (preload) expose quelques fonctions nommées. Le processus de rendu (renderer), lui, se contente d’afficher la liste et d’appeler ces fonctions.
La plupart des tutoriels Electron consacrés aux gestionnaires de fichiers datent de 2016 à 2021. Ils activent nodeIntegration, appellent require('fs') depuis la page et s’appuient sur remote. Un code écrit de cette manière ne fonctionne plus avec les versions actuelles d’Electron, ou bien laisse une faille de sécurité béante. Ce guide construit un explorateur de fichiers fonctionnel selon le modèle actuel : un renderer en bac à sable (sandbox), une passerelle preload restreinte et des handlers dans le processus principal qui vérifient chaque chemin reçu. Si vous n’avez jamais créé d’application Electron, commencez par lire Building Desktop Apps with Electron.
Points clés à retenir
- Le module
shellne fonctionne pas dans un renderer sandboxé :shell.openPathetshell.trashItemdoivent donc s’exécuter dans le processus principal, derrière un canalipcMain.handle. shell.openPathne rejette pas sa promesse en cas d’échec. Elle est résolue avec un message d’erreur, et seule une chaîne vide signifie que le fichier a bien été ouvert.- La fonction
fs.renamede Node écrase la destination si elle existe déjà. Vérifiez donc que le nom cible est libre avant de renommer. - Chaque fonction du preload doit encapsuler un seul canal IPC. Une fonction générique
invoke(channel, ...args)permettrait à n’importe quel script de la page d’appeler tous les handlers que vous enregistrez. - Considérez chaque chemin envoyé par le renderer comme non fiable. Résolvez-le dans le processus principal, comparez-le au dossier choisi par l’utilisateur et refusez tout ce qui se trouve en dehors.
Ce que vous allez construire : un gestionnaire de fichiers Electron
L’application remplit cinq fonctions : lister le contenu d’un dossier, ouvrir des sous-dossiers et des fichiers, afficher la taille et la date de modification de chaque élément, renommer des éléments et les placer dans la corbeille. Le tableau ci-dessous indique où s’exécute chaque opération.
| Fonctionnalité | S’exécute dans | API | Canal IPC |
|---|---|---|---|
| Choisir le dossier racine | Main | dialog.showOpenDialog | dialog:pickFolder |
| Lister un dossier | Main | fs.readdir + fs.stat | fs:list |
| Ouvrir un sous-dossier | Renderer → Main | fs:list à nouveau | fs:list |
| Ouvrir un fichier | Main | shell.openPath | shell:open |
| Renommer | Main | fs.rename | fs:rename |
| Placer dans la corbeille | Main | shell.trashItem | shell:trash |
Configuration du projet et webPreferences sécurisées
Générez la structure du projet avec le template Vite d’Electron Forge :
npx create-electron-app@latest my-app --template=vite
Forge qualifie sa prise en charge de Vite d’expérimentale. Si vous préférez une option plus éprouvée, utilisez --template=webpack.
D’après la checklist de sécurité d’Electron, l’intégration de Node est désactivée par défaut depuis Electron 5, l’isolation de contexte activée depuis la version 12 et le sandbox activé depuis la version 20. Définissez malgré tout ces trois options explicitement, afin que personne n’ait à se souvenir des valeurs par défaut en lisant le code :
mainWindow = new BrowserWindow({
width: 960,
height: 640,
webPreferences: {
preload: path.join(__dirname, 'preload.cjs'),
contextIsolation: true, // preload and page get separate JS worlds
nodeIntegration: false, // no require() in the page
sandbox: true, // renderer runs under Chromium's sandbox
},
});
// keep the template's existing loadURL / loadFile lines below this
Le template Vite de Forge 8 compile le script de préchargement sous le nom preload.cjs. Si le fichier main.js généré utilise un autre nom de fichier, conservez celui qu’il contient déjà.
Désactiver l’isolation de contexte désactive aussi le sandbox du renderer, quelle que soit la valeur de l’option sandbox. Un preload sandboxé ne peut faire que require('electron') (ou electron/renderer / electron/common). La page Process Sandboxing exclut les modules natifs de Node, Buffer et les fichiers locaux : le preload doit donc tenir en un seul fichier ou être regroupé en un seul bundle.
Processus principal : handlers pour le système de fichiers et le shell
Dans un gestionnaire de fichiers Electron, tout le travail privilégié s’effectue dans le processus principal, dans src/main.js. Le module shell peut être utilisé dans un renderer, mais il ne fonctionne pas dans un renderer sandboxé. L’ouverture des fichiers et leur envoi à la corbeille passent donc eux aussi par l’IPC.
const { app, BrowserWindow, ipcMain, dialog, shell } = require('electron');
const path = require('node:path');
const fs = require('node:fs/promises');
let mainWindow = null;
let rootDir = null; // set only by the folder picker
function assertSender(event) {
if (BrowserWindow.fromWebContents(event.sender) !== mainWindow) {
throw new Error('Untrusted sender');
}
}
function insideRoot(target) {
const rel = path.relative(rootDir, target);
return rel === '' ||
(rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
}
async function resolveInRoot(p) {
if (!rootDir) throw new Error('Pick a folder first');
const abs = await fs.realpath(path.resolve(String(p)));
if (!insideRoot(abs)) throw new Error('Path is outside the chosen folder');
return abs;
}
// Realpath the parent only, so rename/trash act on a symlink, not its target
async function resolveEntry(p) {
const abs = path.resolve(String(p));
const parent = await resolveInRoot(path.dirname(abs));
return path.join(parent, path.basename(abs));
}
function handle(channel, fn) {
ipcMain.handle(channel, async (event, ...args) => {
assertSender(event);
return fn(...args);
});
}
handle('fs:list', async (dir) => {
const abs = await resolveInRoot(dir ?? rootDir);
const dirents = await fs.readdir(abs, { withFileTypes: true });
const settled = await Promise.allSettled(dirents.map(async (d) => {
const full = path.join(abs, d.name);
const st = await fs.stat(full);
return { name: d.name, path: full, isDir: st.isDirectory(),
isLink: d.isSymbolicLink(), size: st.size, mtimeMs: st.mtimeMs };
}));
const entries = settled.filter((r) => r.status === 'fulfilled').map((r) => r.value)
.sort((a, b) => (b.isDir - a.isDir) || a.name.localeCompare(b.name));
return { dir: abs, entries };
});
handle('fs:rename', async (target, newName) => {
const name = String(newName).trim();
if (!name || name === '.' || name === '..' || name.includes('/') || name.includes(path.sep)) {
throw new Error('Invalid file name');
}
const src = await resolveEntry(target);
const dest = path.join(path.dirname(src), name);
if (!insideRoot(dest)) throw new Error('Path is outside the chosen folder');
const taken = await fs.access(dest).then(() => true, () => false);
if (taken) throw new Error(`"${name}" already exists`);
await fs.rename(src, dest);
});
handle('shell:open', async (target) => {
const err = await shell.openPath(await resolveInRoot(target));
if (err) throw new Error(err);
});
handle('shell:trash', async (target) => {
const abs = await resolveEntry(target);
if (abs === rootDir) throw new Error('Cannot trash the root folder');
await shell.trashItem(path.resolve(abs));
});
Voici le rôle de chaque partie du code du processus principal :
- Listage.
fs.readdiravec l’optionwithFileTypesrenvoie des objetsDirent.fs.staty ajoute la taille et la date de modification.Promise.allSettledempêche un seul lien symbolique cassé de faire échouer tout le listage. - Objets simples uniquement. Chaque élément est converti en données simples, car l’IPC utilise l’algorithme Structured Clone : une instance
fs.Statsperdrait ses méthodes lors du transfert. - Renommage. La fonction
fs.renamede Node remplace silencieusementnewPaths’il existe déjà, d’où la vérification préalable dans le handler. Il subsiste une courte fenêtre entre la vérification et le renommage, ce qui reste acceptable pour un outil de bureau. - Ouverture.
shell.openPathest résolue avec le message d’erreur si l’ouverture a échoué, et avec une chaîne vide sinon. Le handler convertit toute chaîne non vide en erreur levée. - Corbeille.
shell.trashItemdéplace l’élément vers la corbeille de la plateforme au lieu de le supprimer définitivement. La promesse est rejetée si une erreur survient lors de la suppression de l’élément demandé. La documentation deshellexige des séparateurs natifs, c’est pourquoi le chemin passe parpath.resolve().
Preload : une API nommée et restreinte
Le script de préchargement expose cinq fonctions nommées au renderer, et rien d’autre. Les anciens tutoriels procédaient ainsi. À proscrire :
// Outdated pattern. Never ship this.
webPreferences: { nodeIntegration: true, contextIsolation: false }
const fs = require('fs'); // in the page
Voici l’approche actuelle, dans src/preload.js :
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('electronAPI', {
listDir: (dir) => ipcRenderer.invoke('fs:list', dir),
pickFolder: () => ipcRenderer.invoke('dialog:pickFolder'),
openPath: (p) => ipcRenderer.invoke('shell:open', p),
rename: (p, newName) => ipcRenderer.invoke('fs:rename', p, newName),
trash: (p) => ipcRenderer.invoke('shell:trash', p),
});
Le nom du canal IPC est codé en dur dans chaque fonction du preload. N’écrivez jamais invoke: (...a) => ipcRenderer.invoke(...a), car cela donnerait à la page l’accès à tous les handlers que vous enregistrez. Notez également que lorsqu’un handler enregistré avec ipcMain.handle lève une exception, le renderer ne reçoit que la propriété message de l’erreur. Rédigez donc des messages compréhensibles par l’utilisateur. Si un appel IPC reste bloqué ou échoue sans explication, Debugging and Troubleshooting Common Electron Issues explique comment distinguer les erreurs du processus principal de celles du renderer.
Renderer : lister, ouvrir, renommer, mettre à la corbeille
Le renderer n’interagit qu’avec le DOM et window.electronAPI. Les noms de fichiers pouvant contenir du balisage, affectez-les via textContent, jamais via innerHTML.
Commencez par fournir à la page une structure dans laquelle effectuer le rendu. Remplacez le <body> du fichier index.html du template par ce balisage, en conservant la balise <script> du template qui charge src/renderer.js :
<body>
<header>
<button id="pick">Choose folder</button>
<button id="up">Up</button>
<span id="status" role="status"></span>
</header>
<ul id="list"></ul>
<dialog id="rename-dialog">
<form method="dialog">
<label>New name <input id="rename-input" required></label>
<button value="cancel" formnovalidate>Cancel</button>
<button value="ok">Rename</button>
</form>
</dialog>
<script type="module" src="/src/renderer.js"></script>
</body>
Electron n’implémente pas window.prompt() : la boîte de renommage est donc un élément <dialog>. Remplacez ensuite le contenu de src/renderer.js :
const api = window.electronAPI;
const list = document.querySelector('#list');
const status = document.querySelector('#status');
const renameDialog = document.querySelector('#rename-dialog');
const renameInput = document.querySelector('#rename-input');
let cwd = null;
function askName(current) {
renameInput.value = current;
renameDialog.returnValue = '';
renameDialog.showModal();
return new Promise((resolve) => {
renameDialog.addEventListener('close', () =>
resolve(renameDialog.returnValue === 'ok' ? renameInput.value : null), { once: true });
});
}
const fmtSize = (n) => {
const u = ['B', 'KB', 'MB', 'GB', 'TB']; let i = 0;
while (n >= 1024 && i < u.length - 1) { n /= 1024; i++; }
return `${n.toFixed(i ? 1 : 0)} ${u[i]}`;
};
async function run(fn) {
try { status.textContent = ''; await fn(); }
catch (err) { status.textContent = err.message; }
}
async function load(dir) {
const res = await api.listDir(dir);
cwd = res.dir;
list.replaceChildren(...res.entries.map(row));
}
function button(label, onClick) {
const b = document.createElement('button');
b.textContent = label;
b.addEventListener('click', (e) => { e.stopPropagation(); run(onClick); });
return b;
}
function row(entry) {
const li = document.createElement('li');
const cells = [entry.isDir ? `${entry.name}/` : entry.name,
entry.isDir ? '' : fmtSize(entry.size),
new Date(entry.mtimeMs).toLocaleString()];
for (const text of cells) {
const span = document.createElement('span');
span.textContent = text;
li.append(span);
}
li.append(
button('Rename', async () => {
const name = await askName(entry.name);
if (name && name !== entry.name) { await api.rename(entry.path, name); await load(cwd); }
}),
button('Trash', async () => {
if (confirm(`Move "${entry.name}" to the trash?`)) { await api.trash(entry.path); await load(cwd); }
}),
);
li.addEventListener('dblclick', () =>
run(() => (entry.isDir ? load(entry.path) : api.openPath(entry.path))));
return li;
}
document.querySelector('#up').addEventListener('click', () => run(() => load(`${cwd}/..`)));
Un double-clic sur un dossier affiche son contenu. Un double-clic sur un fichier le transmet au système d’exploitation. Le bouton Up envoie cwd/... Une fois la racine atteinte, le processus principal refuse la requête et la ligne d’état affiche l’erreur.
Sélecteur de dossier avec dialog.showOpenDialog
Le dossier racine provient exclusivement d’une boîte de dialogue native ouverte par le processus principal, et il n’est stocké que dans ce dernier. Le renderer n’envoie jamais de racine : il envoie des chemins, que le processus principal compare à la racine qu’il détient déjà. Ajoutez ce handler à main.js :
handle('dialog:pickFolder', async () => {
const { canceled, filePaths } = await dialog.showOpenDialog(mainWindow, {
properties: ['openDirectory'],
});
if (canceled) return null;
rootDir = await fs.realpath(filePaths[0]);
return rootDir;
});
Dans l’API dialog, c’est la propriété openDirectory qui permet de sélectionner des répertoires. Passer la fenêtre en premier argument la définit comme parente de la boîte de dialogue, ce qui rend cette dernière modale. La racine passe une seule fois par realpath, à cet endroit. Ainsi, un lien symbolique situé dans le dossier et pointant ailleurs se résout en dehors de la racine et échoue au contrôle insideRoot.
Branchez le sélecteur dans le renderer :
document.querySelector('#pick').addEventListener('click', () => run(async () => {
const dir = await api.pickFolder();
if (dir) await load(dir);
}));
Renforcement de la sécurité : chemins, émetteurs et CSP
Trois mécanismes de contrôle font de cet explorateur de fichiers Electron une base sûre sur laquelle construire :
- Confinement des chemins. Chaque handler fait passer les données du renderer par
resolveInRootouresolveEntry. Ces deux fonctions résolvent les liens symboliques et utilisentpath.relativepour rejeter tout chemin qui sort de la racine ou qui pointe vers un autre lecteur Windows. - Validation de l’émetteur. La checklist de sécurité recommande de valider l’émetteur des messages IPC, car n’importe quelle frame peut en envoyer.
assertSendern’accepte que les appels provenant duwebContentsdemainWindow. - Content Security Policy. Une page chargée depuis
file://ne peut pas recevoir de CSP via un en-tête HTTP. Ajoutez donc une balise meta dansindex.html:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
Vous pouvez également bloquer la navigation et l’ouverture de nouvelles fenêtres dans le processus principal :
mainWindow.webContents.on('will-navigate', (e) => e.preventDefault());
mainWindow.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
Conclusion
Vous disposez désormais d’un gestionnaire de fichiers Electron sécurisé. Le processus principal contrôle le système de fichiers et le dossier racine, le preload expose cinq fonctions fixes, et le renderer ne peut accéder à rien que vous ne lui ayez explicitement fourni. Pour l’enrichir, procédez toujours de la même manière : un nouveau handler dans le processus principal, une nouvelle fonction dans le preload, et les mêmes contrôles de chemin et d’émetteur pour chacun. Lorsque vous serez prêt à distribuer votre application, suivez le guide Packaging and Distributing Electron Apps. Si l’empreinte d’Electron vous préoccupe pour ce type d’outil, consultez Comparing Electron and Tauri for Desktop Applications.
FAQ
Pourquoi prompt() lève-t-il une erreur dans un renderer Electron ?
Electron n'implémente pas window.prompt() : l'appeler lève donc une erreur au lieu d'ouvrir une boîte de dialogue. Les fonctions alert() et confirm(), en revanche, fonctionnent dans Electron. Pour demander un nouveau nom de fichier, utilisez un champ de saisie intégré à la page ou un élément HTML dialog. Vous pouvez aussi ouvrir une petite BrowserWindow modale depuis le processus principal et renvoyer la valeur saisie via l'IPC.
Comment obtenir le chemin réel d'un fichier déposé sur une fenêtre Electron ?
Appelez webUtils.getPathForFile(file) dans le script de préchargement et exposez-le via contextBridge. Electron 32 a supprimé la propriété non standard File.path de l'objet File du Web : un code qui lit file.path n'obtient donc plus de chemin. Envoyez le chemin renvoyé à un handler du processus principal et appliquez-lui le même contrôle de dossier racine qu'à toute autre donnée provenant du renderer.
Comment actualiser automatiquement la liste des fichiers lorsque ceux-ci changent sur le disque ?
Surveillez le dossier affiché avec fs.watch dans le processus principal, puis envoyez une notification à la page avec mainWindow.webContents.send. Dans le preload, encapsulez ipcRenderer.on de façon à appeler le callback du renderer sans l'objet event, car transmettre cet objet exposerait ipcRenderer à la page. Considérez chaque événement uniquement comme un signal pour relancer fs:list. Node ne signale que les événements « rename » et « change », et le nom de fichier peut être null.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.
Star on GitHub12k