Crie um gerenciador de arquivos desktop com Electron
Crie um gerenciador de arquivos seguro com Electron, renderer isolado, ponte IPC preload e handlers main para navegar, abrir, renomear e mover arquivos para a lixeira.
Um gerenciador de arquivos em Electron divide o trabalho entre três processos. O processo principal (main) executa todas as operações de sistema de arquivos e de shell, o script de preload expõe algumas funções nomeadas, e o renderer apenas desenha a lista e chama essas funções.
A maioria dos tutoriais de gerenciador de arquivos para Electron é de 2016 a 2021. Eles ativam o nodeIntegration, chamam require('fs') diretamente na página e recorrem ao remote. Código escrito dessa forma ou quebra nas versões atuais do Electron ou deixa uma brecha de segurança aberta. Este guia constrói um navegador de arquivos funcional usando o modelo atual: um renderer em sandbox, uma ponte de preload enxuta e handlers no processo principal que validam todos os caminhos que recebem. Se você nunca criou um app com Electron, leia primeiro Building Desktop Apps with Electron.
Principais conclusões
- O módulo
shellnão funciona em um renderer com sandbox, entãoshell.openPatheshell.trashItemprecisam rodar no processo principal, atrás de um canalipcMain.handle. shell.openPathnão rejeita a promise em caso de falha. Ela é resolvida com uma mensagem de erro, e apenas uma string vazia indica que o arquivo foi aberto.- O
fs.renamedo Node sobrescreve um destino existente, então verifique se o nome de destino está livre antes de renomear. - Cada função do preload deve encapsular exatamente um canal IPC. Um
invoke(channel, ...args)genérico permite que qualquer script da página chame todos os handlers que você registrar. - Trate todo caminho enviado pelo renderer como não confiável. Resolva-o no main, compare-o com a pasta escolhida pelo usuário e recuse qualquer coisa fora dela.
O que você vai construir: um gerenciador de arquivos em Electron
O app faz cinco coisas: lista uma pasta, abre subpastas e arquivos, mostra o tamanho e a data de modificação de cada entrada, renomeia entradas e as move para a lixeira. A tabela mostra onde cada operação é executada.
| Funcionalidade | Executa em | API | Canal IPC |
|---|---|---|---|
| Escolher pasta raiz | Main | dialog.showOpenDialog | dialog:pickFolder |
| Listar pasta | Main | fs.readdir + fs.stat | fs:list |
| Abrir subpasta | Renderer → Main | fs:list novamente | fs:list |
| Abrir arquivo | Main | shell.openPath | shell:open |
| Renomear | Main | fs.rename | fs:rename |
| Mover para a lixeira | Main | shell.trashItem | shell:trash |
Configuração do projeto e webPreferences seguras
Crie a estrutura do projeto com o template Vite do Electron Forge:
npx create-electron-app@latest my-app --template=vite
O Forge classifica seu suporte ao Vite como experimental. Se preferir uma opção mais conservadora, use --template=webpack.
De acordo com o checklist de segurança do Electron, a integração com Node vem desativada por padrão desde o Electron 5, o isolamento de contexto vem ativado desde o 12 e o sandbox desde o 20. Mesmo assim, defina as três opções explicitamente, para que ninguém que leia o código precise lembrar dos valores padrão:
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
O template Vite do Forge 8 gera o script de preload como preload.cjs. Se o main.js gerado no seu projeto usar outro nome de arquivo, mantenha o que já está lá.
Desativar o isolamento de contexto também desativa o sandbox do renderer, independentemente do valor da opção sandbox. Um preload em sandbox só pode fazer require('electron') (ou electron/renderer / electron/common). A documentação de Process Sandboxing proíbe módulos nativos do Node, Buffer e arquivos locais, então o preload precisa ser um único arquivo ou ser empacotado (bundled) em um só.
Processo principal: handlers de sistema de arquivos e de shell
Em um gerenciador de arquivos com Electron, todo o trabalho privilegiado acontece no processo principal, em src/main.js. O módulo shell pode ser usado em um renderer, mas não funciona em um renderer com sandbox. Isso significa que abrir arquivos e enviá-los para a lixeira também passa pelo 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));
});
Veja o que cada parte do código do processo principal faz:
- Listagem.
fs.readdircomwithFileTypesretorna objetosDirent. Ofs.statacrescenta o tamanho e a data de modificação. OPromise.allSettledevita que um único symlink quebrado faça a listagem inteira falhar. - Apenas objetos simples. Cada entrada é mapeada para dados simples porque o IPC usa o algoritmo Structured Clone, e uma instância de
fs.Statsperderia seus métodos no caminho. - Renomear. O
fs.renamedo Node substitui silenciosamente onewPathse ele já existir, e é por isso que o handler verifica antes. Existe uma pequena janela de tempo entre a verificação e a renomeação, o que é aceitável para uma ferramenta desktop. - Abrir.
shell.openPathé resolvida com a mensagem de erro se a abertura falhar e com uma string vazia caso contrário. O handler converte uma string não vazia em um erro lançado. - Lixeira.
shell.trashItemmove o item para a lixeira da plataforma em vez de excluí-lo permanentemente. Ela rejeita a promise se ocorrer um erro ao excluir o item solicitado. A documentação doshellexige separadores nativos, e é por isso que o caminho passa porpath.resolve().
Preload: uma API pequena e nomeada
O script de preload expõe cinco funções nomeadas para o renderer e nada além disso. Tutoriais antigos faziam assim. Não faça:
// Outdated pattern. Never ship this.
webPreferences: { nodeIntegration: true, contextIsolation: false }
const fs = require('fs'); // in the page
Este é o padrão atual, em 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 função do preload tem o nome do seu canal IPC fixo no código. Nunca escreva invoke: (...a) => ipcRenderer.invoke(...a), porque isso dá à página acesso a todos os handlers que você registrar. Observe também que, quando um handler registrado com ipcMain.handle lança um erro, o renderer recebe apenas a message do erro. Escreva mensagens que um usuário consiga entender. Se uma chamada IPC travar ou falhar sem explicação, Debugging and Troubleshooting Common Electron Issues explica como distinguir falhas do processo principal de falhas do renderer.
Renderer: listar, abrir, renomear, enviar para a lixeira
O renderer só mexe no DOM e em window.electronAPI. Nomes de arquivo podem conter marcação, então defina-os com textContent e nunca com innerHTML.
Primeiro, dê à página um lugar onde renderizar o conteúdo. Substitua o <body> do index.html do template por esta marcação, mantendo a tag <script> do template 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>
O Electron não implementa window.prompt(), então a caixa de renomeação é um <dialog>. Em seguida, substitua o conteúdo 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}/..`)));
Um clique duplo em uma pasta lista seu conteúdo. Um clique duplo em um arquivo o repassa ao sistema operacional. O botão Up envia cwd/... Ao chegar à raiz, o main recusa a requisição e a linha de status exibe o erro.
Seletor de pastas com dialog.showOpenDialog
A pasta raiz vem exclusivamente de um diálogo nativo no main e é armazenada exclusivamente no main. O renderer nunca envia uma raiz. Ele envia caminhos, e o main os valida em relação à raiz que já possui. Adicione este handler ao 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;
});
Na API dialog, a propriedade openDirectory é o que permite selecionar diretórios. Passar a janela como primeiro argumento a vincula ao diálogo como janela pai, o que torna o diálogo modal. A raiz passa pelo realpath uma única vez, aqui. Dessa forma, um symlink dentro da pasta que aponte para outro lugar é resolvido para fora da raiz e falha na verificação de insideRoot.
Conecte o seletor no renderer:
document.querySelector('#pick').addEventListener('click', () => run(async () => {
const dir = await api.pickFolder();
if (dir) await load(dir);
}));
Hardening: caminhos, remetentes e CSP
Três controles tornam este navegador de arquivos em Electron uma base segura para evoluir:
- Contenção de caminhos. Todo handler passa a entrada vinda do renderer por
resolveInRootouresolveEntry. Ambas resolvem symlinks e usampath.relativepara rejeitar qualquer coisa que tente sair da raiz ou que caia em outra unidade no Windows. - Validação do remetente. O checklist de segurança recomenda validar o remetente das mensagens IPC, porque qualquer frame pode enviá-las.
assertSenderaceita chamadas apenas dowebContentsdemainWindow. - Content Security Policy. Uma página carregada via
file://não pode receber a CSP como cabeçalho HTTP, então adicione uma meta tag aoindex.html:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
Opcionalmente, bloqueie a navegação e a abertura de novas janelas no main:
mainWindow.webContents.on('will-navigate', (e) => e.preventDefault());
mainWindow.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));
Conclusão
Agora você tem um gerenciador de arquivos seguro em Electron. O main controla o sistema de arquivos e a pasta raiz, o preload expõe cinco funções fixas e o renderer não consegue acessar nada que você não tenha entregado a ele. Estenda o app sempre da mesma forma: um novo handler no main, uma nova função no preload e as mesmas verificações de caminho e de remetente em cada um. Quando estiver pronto para distribuir, siga Packaging and Distributing Electron Apps. Se o consumo de recursos do Electron for uma preocupação para esse tipo de ferramenta, veja Comparing Electron and Tauri for Desktop Applications.
Perguntas frequentes
Por que prompt() lança um erro em um renderer do Electron?
O Electron não implementa window.prompt(), então chamá-lo lança um erro em vez de abrir um diálogo. As funções alert() e confirm() funcionam no Electron. Para pedir um novo nome de arquivo, use um campo de texto na própria página ou um elemento HTML dialog. Você também pode abrir uma pequena BrowserWindow modal a partir do processo principal e enviar o valor digitado de volta via IPC.
Como obtenho o caminho real de um arquivo arrastado para uma janela do Electron?
Chame webUtils.getPathForFile(file) no script de preload e exponha-o por meio do contextBridge. O Electron 32 removeu a propriedade não padrão File.path do objeto File da Web, então código que lê file.path não obtém mais um caminho. Envie o caminho retornado para um handler no processo principal e aplique a ele a mesma verificação de pasta raiz usada para qualquer outra entrada vinda do renderer.
Como fazer a lista de arquivos ser atualizada automaticamente quando os arquivos mudam no disco?
Monitore a pasta listada com fs.watch no processo principal e envie uma notificação para a página com mainWindow.webContents.send. No preload, encapsule ipcRenderer.on para que ele chame o callback do renderer sem o objeto de evento, porque repassar o evento expõe o ipcRenderer à página. Trate cada evento apenas como um sinal para executar fs:list novamente. O Node informa apenas 'rename' e 'change', e o nome do arquivo pode 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