mommy-lectron

Uma toolkit pequena, rápida e segura para deixar apps Electron em JavaScript puro mais agradáveis de construir. Ela simplifica UI, eventos, estado local, logs no processo principal e controles básicos da janela, sem habilitar Node.js no renderer.

Requisitos

• Node.js 18 ou superior
• Electron 28 ou superior
• JavaScript — este projeto não usa TypeScript.

Instalação

npm install mommy-lectron electron

Quick start seguro

No processo principal, crie a janela com isolamento de contexto e registre somente os canais IPC que a biblioteca precisa:

// main.js
const path = require("node:path");
const { app, BrowserWindow, ipcMain } = require("electron");
const { registerMommyIpc } = require("mommy-lectron/main");

app.whenReady().then(() => {
  registerMommyIpc({ ipcMain, BrowserWindow });
  const window = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, "preload.js"),
      contextIsolation: true,
      nodeIntegration: false
    }
  });
  window.loadFile("index.html");
});

No preload, exponha a ponte limitada:

// preload.js
const { contextBridge, ipcRenderer } = require("electron");
const { exposeMommyBridge } = require("mommy-lectron/preload");

exposeMommyBridge({ contextBridge, ipcRenderer });

Em uma página sem bundler, carregue o arquivo de browser distribuído pelo pacote. Ele expõe window.mommy:

<h1 id="title">Esperando...</h1>
<input id="name" placeholder="Seu nome">
<button id="hello">Cumprimentar</button>
<script src="./node_modules/mommy-lectron/dist/mommy-lectron.js"></script>
<script>
  mommy.action("#hello", () => {
    const name = mommy.value("#name") || "visitante";
    mommy.set("user", name);
    mommy.text("#title", `Olá, ${mommy.get("user")}!`);
    mommy.log("Greeting sent", { name });
  });
</script>

Se o seu projeto já empacota JavaScript para o renderer, use const mommy = require("mommy-lectron") no módulo de renderer em vez do arquivo dist.

API

UI

Todas as operações de escrita afetam todos os elementos que correspondem ao seletor e retornam mommy, permitindo encadeamento.

mommy.text("#status", "Salvo!");
const label = mommy.text("#status");

mommy.hide("#menu").show("#panel");
mommy.disable("#send").enable("#cancel");

mommy.setValue("#email", "[email protected]");
const email = mommy.value("#email");

mommy.addClass("#status", "success");
mommy.removeClass("#status", "loading");
mommy.toggleClass("#panel", "open");
const buttons = mommy.elements("button");

text(selector) e value(selector) leem o primeiro elemento. Se nenhum elemento corresponder, lançam um erro claro; isso evita falhas silenciosas.

Eventos

function save() {
  mommy.text("#status", "Salvo!");
}

mommy.on("#save", "click", save);
mommy.off("#save", "click", save);
mommy.action("#save", save); // atalho para evento click

Registrar a mesma função, no mesmo elemento e evento, não duplica listener.

Estado local

O estado é um Map em memória do renderer: síncrono, pequeno e sem persistência implícita.

mommy.set("user", "João");
mommy.get("user");
mommy.get("theme", "light");
mommy.has("user");
mommy.delete("user");
mommy.clear();

Logs e janela Electron

Com o preload e o registro do main configurados, os logs seguem ao terminal do processo principal. Sem a ponte, eles usam o console local (útil em testes e navegador).

mommy.log("Started");
mommy.info("Connected", { port: 3000 });
mommy.warn("Low disk space");
mommy.error("Could not save");

await mommy.minimize();
await mommy.maximize();
await mommy.restore();
await mommy.close();

Arquitetura e segurança

src/renderer contém a API de DOM, eventos, estado e logs. src/preload expõe somente log e quatro ações de janela por contextBridge. src/main aceita apenas níveis de log e ações em uma lista fechada, e sempre encontra a BrowserWindow a partir do remetente do IPC — portanto um renderer não escolhe outra janela nem executa comandos arbitrários.

O fluxo é renderer → preload → IPC → main. Mantenha contextIsolation: true e nodeIntegration: false; não exponha ipcRenderer, require ou módulos Node diretamente ao renderer.

Desenvolvimento e testes

npm run build       # gera dist/mommy-lectron.js
npm test            # testes com node:test, sem janela gráfica
npm run check       # valida sintaxe JavaScript
npm run pack:check  # mostra exatamente o conteúdo do pacote

Há um app demonstrativo em examples/secure-app. Após instalar Electron como dependência de desenvolvimento/local e executar npm run build, adapte-o ao seu app ou execute Electron apontando para essa pasta.

Publicação no NPM

Antes de publicar, confirme os arquivos com npm run pack:check. Depois de autenticar-se, publique manualmente com:

npm publish

O hook prepublishOnly executa build, checagem e testes. Este repositório não publica automaticamente.

Licença

MIT.