Cómo crear un gestor de archivos de escritorio con Electron
Crea un gestor de archivos seguro con Electron, un renderizador aislado, un puente IPC preload y controladores main para explorar, abrir, renombrar y enviar archivos a la papelera.
Un gestor de archivos en Electron reparte el trabajo entre tres procesos. El proceso principal ejecuta todas las operaciones del sistema de archivos y del shell, el script de preload expone unas pocas funciones con nombre y el renderer se limita a dibujar la lista y a llamar a esas funciones.
La mayoría de los tutoriales sobre gestores de archivos con Electron que se encuentran por ahí datan de entre 2016 y 2021. Activan nodeIntegration, llaman a require('fs') desde la página y recurren a remote. El código escrito de esa manera o bien deja de funcionar en las versiones actuales de Electron, o bien deja abierto un agujero de seguridad. Esta guía construye un explorador de archivos funcional con el modelo actual: un renderer en sandbox, un puente de preload reducido y handlers en el proceso principal que validan cada ruta que reciben. Si nunca has creado una aplicación con Electron, lee primero Building Desktop Apps with Electron.
Puntos clave
- El módulo
shellno funciona en un renderer en sandbox, por lo queshell.openPathyshell.trashItemdeben ejecutarse en el proceso principal, detrás de un canalipcMain.handle. shell.openPathno rechaza la promesa cuando falla. Se resuelve con un mensaje de error, y solo una cadena vacía indica que el archivo se abrió.fs.renamede Node sobrescribe el destino si ya existe, así que comprueba que el nombre de destino esté libre antes de renombrar.- Cada función del preload debe envolver exactamente un canal IPC. Un
invoke(channel, ...args)genérico permite que cualquier script de la página llame a todos los handlers que registres. - Trata toda ruta que envíe el renderer como no confiable. Resuélvela en el proceso principal, compárala con la carpeta que eligió el usuario y rechaza cualquier cosa que quede fuera de esa carpeta.
Qué vas a construir: un gestor de archivos con Electron
La aplicación hace cinco cosas: lista una carpeta, abre subcarpetas y archivos, muestra el tamaño y la fecha de modificación de cada entrada, renombra entradas y las mueve a la papelera. La tabla muestra dónde se ejecuta cada operación.
| Funcionalidad | Se ejecuta en | API | Canal IPC |
|---|---|---|---|
| Elegir la carpeta raíz | Main | dialog.showOpenDialog | dialog:pickFolder |
| Listar carpeta | Main | fs.readdir + fs.stat | fs:list |
| Abrir subcarpeta | Renderer → Main | fs:list de nuevo | fs:list |
| Abrir archivo | Main | shell.openPath | shell:open |
| Renombrar | Main | fs.rename | fs:rename |
| Mover a la papelera | Main | shell.trashItem | shell:trash |
Configuración del proyecto y webPreferences seguras
Genera la estructura del proyecto con la plantilla Vite de Electron Forge:
npx create-electron-app@latest my-app --template=vite
Forge considera experimental su soporte para Vite. Si prefieres la opción más conservadora, usa --template=webpack.
Según la lista de verificación de seguridad de Electron, la integración con Node está desactivada por defecto desde Electron 5, el aislamiento de contexto activado desde la 12 y el sandbox activado desde la 20. Aun así, configura las tres opciones de forma explícita para que nadie que lea el código tenga que recordar los valores por defecto:
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
La plantilla Vite de Forge 8 compila el script de preload como preload.cjs. Si el main.js generado usa otro nombre de archivo, conserva el que ya tiene.
Desactivar el aislamiento de contexto también desactiva el sandbox del renderer, independientemente de lo que indique la opción sandbox. Un preload en sandbox solo puede hacer require('electron') (o electron/renderer / electron/common). Process Sandboxing excluye los módulos integrados de Node, Buffer y los archivos locales, por lo que el preload debe ser un único archivo o empaquetarse en uno solo.
Proceso principal: handlers del sistema de archivos y del shell
En un gestor de archivos con Electron, todo el trabajo privilegiado ocurre en el proceso principal, en src/main.js. El módulo shell puede usarse en un renderer, pero no funciona en uno en sandbox. Eso significa que abrir archivos y enviarlos a la papelera también tiene que pasar por 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));
});
Esto es lo que hace cada parte del código del proceso principal:
- Listado.
fs.readdirconwithFileTypesdevuelve objetosDirent.fs.statañade el tamaño y la fecha de modificación.Promise.allSettledevita que un único enlace simbólico roto haga fallar todo el listado. - Solo objetos planos. Cada entrada se convierte en datos planos porque IPC utiliza el algoritmo de clonación estructurada (Structured Clone), y una instancia de
fs.Statsperdería sus métodos por el camino. - Renombrar.
fs.renamede Node reemplaza silenciosamentenewPathsi ya existe; por eso el handler lo comprueba primero. Queda una pequeña ventana de tiempo entre la comprobación y el renombrado, algo aceptable para una herramienta de escritorio. - Abrir.
shell.openPathse resuelve con el mensaje de error si la apertura falló, y con una cadena vacía en caso contrario. El handler convierte una cadena no vacía en un error lanzado. - Papelera.
shell.trashItemmueve el elemento a la papelera de la plataforma en lugar de eliminarlo de forma permanente. Rechaza la promesa si se produce un error al eliminar el elemento solicitado. La documentación deshellexige separadores nativos, por eso la ruta pasa porpath.resolve().
Preload: una API pequeña con funciones con nombre
El script de preload expone al renderer cinco funciones con nombre y nada más. Los tutoriales antiguos lo hacían así. No lo hagas:
// Outdated pattern. Never ship this.
webPreferences: { nodeIntegration: true, contextIsolation: false }
const fs = require('fs'); // in the page
Este es el patrón actual, en 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),
});
Cada función del preload tiene el nombre de su canal IPC escrito directamente en el código. Nunca escribas invoke: (...a) => ipcRenderer.invoke(...a), porque da a la página acceso a todos los handlers que registres. Ten en cuenta también que, cuando un handler registrado con ipcMain.handle lanza un error, el renderer solo recibe la propiedad message del error. Escribe mensajes que un usuario pueda entender. Si una llamada IPC se queda colgada o falla sin explicación, Debugging and Troubleshooting Common Electron Issues explica cómo distinguir los fallos del proceso principal de los del renderer.
Renderer: listar, abrir, renombrar y enviar a la papelera
El renderer solo interactúa con el DOM y con window.electronAPI. Los nombres de archivo pueden contener marcado, así que asígnalos con textContent y nunca con innerHTML.
Primero, dale a la página un lugar donde renderizar. Sustituye el <body> del index.html de la plantilla por este marcado, conservando la etiqueta <script> de la plantilla para 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 no implementa window.prompt(), así que el cuadro para renombrar es un <dialog>. A continuación, sustituye el contenido 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}/..`)));
Al hacer doble clic en una carpeta se lista su contenido. Al hacer doble clic en un archivo, este se pasa al sistema operativo. El botón Up envía cwd/... Cuando llegas a la raíz, el proceso principal rechaza la petición y la línea de estado muestra el error.
Selector de carpetas con dialog.showOpenDialog
La carpeta raíz proviene únicamente de un diálogo nativo en el proceso principal y se almacena solo allí. El renderer nunca envía una raíz. Envía rutas, y el proceso principal las valida contra la raíz que ya tiene guardada. Añade este handler a 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;
});
En la API dialog, la propiedad openDirectory es la que permite seleccionar directorios. Pasar la ventana como primer argumento la asigna como ventana padre del diálogo, lo que lo convierte en modal. La raíz pasa por realpath una sola vez, aquí. De esta forma, un enlace simbólico dentro de la carpeta que apunte a otro lugar se resuelve fuera de la raíz y no supera insideRoot.
Conecta el selector en el renderer:
document.querySelector('#pick').addEventListener('click', () => run(async () => {
const dir = await api.pickFolder();
if (dir) await load(dir);
}));
Refuerzo de la seguridad: rutas, emisores y CSP
Tres controles hacen que este explorador de archivos con Electron sea una base segura sobre la que construir:
- Contención de rutas. Todos los handlers pasan la entrada del renderer por
resolveInRootoresolveEntry. Ambas funciones resuelven los enlaces simbólicos y usanpath.relativepara rechazar cualquier ruta que escape de la raíz o que apunte a otra unidad de Windows. - Validación del emisor. La lista de verificación de seguridad indica que hay que validar el emisor de los mensajes IPC, ya que cualquier frame puede enviarlos.
assertSendersolo acepta llamadas procedentes delwebContentsdemainWindow. - Content Security Policy. Una página cargada desde
file://no puede recibir la CSP como cabecera HTTP, así que añade una etiqueta meta aindex.html:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
Opcionalmente, bloquea la navegación y la apertura de nuevas ventanas en el proceso principal:
mainWindow.webContents.on('will-navigate', (e) => e.preventDefault());
mainWindow.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
Conclusión
Ya tienes un gestor de archivos seguro con Electron. El proceso principal controla el sistema de archivos y la carpeta raíz, el preload expone cinco funciones fijas y el renderer no puede acceder a nada que no le hayas proporcionado. Amplíalo siempre de la misma manera: un nuevo handler en el proceso principal, una nueva función en el preload y las mismas comprobaciones de ruta y de emisor en cada uno. Cuando estés listo para distribuirlo, sigue Packaging and Distributing Electron Apps. Si el consumo de recursos de Electron te preocupa para este tipo de herramienta, consulta Comparing Electron and Tauri for Desktop Applications.
Preguntas frecuentes
¿Por qué prompt() lanza un error en un renderer de Electron?
Electron no implementa window.prompt(), así que llamarlo lanza un error en lugar de abrir un diálogo. Las funciones alert() y confirm() sí funcionan en Electron. Para pedir un nuevo nombre de archivo, usa un campo de texto dentro de la página o un elemento dialog de HTML. También puedes abrir una pequeña BrowserWindow modal desde el proceso principal y devolver el valor introducido mediante IPC.
¿Cómo obtengo la ruta real de un archivo arrastrado a una ventana de Electron?
Llama a webUtils.getPathForFile(file) en el script de preload y exponlo mediante contextBridge. Electron 32 eliminó la propiedad no estándar File.path del objeto File de la Web, por lo que el código que lee file.path ya no obtiene ninguna ruta. Envía la ruta devuelta a un handler del proceso principal y aplícale la misma comprobación de carpeta raíz que a cualquier otra entrada del renderer.
¿Cómo puede actualizarse automáticamente la lista de archivos cuando cambian en el disco?
Vigila la carpeta que se está listando con fs.watch en el proceso principal y envía una notificación a la página con mainWindow.webContents.send. En el preload, envuelve ipcRenderer.on para que invoque el callback del renderer sin el objeto event, ya que pasar el evento expone ipcRenderer a la página. Trata cada evento únicamente como una señal para volver a ejecutar fs:list. Node solo informa de 'rename' y 'change', y el nombre del archivo puede ser 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