1. Filosofia de Design: Diferenças Essenciais
A abordagem arquitetônica do Neutralinojs difere significativamente de frameworks mais pesados. Enquento alguns empacotam um navegador e um tempo de execução de servidor completos, o Neutralinojs opta por utilizar os componentes já presentes no sistema operacional do usuário.
┌─────────────────────────────────────────────────────────────────┐
│ Estrutura Convencional (Peso Elevado) │
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────────┐ │
│ │ Navegador Embutido│ │ Tempo de Execução │ │ Seu Código │ │
│ │ (~100MB) │+ │ do Servidor │+ │ (~1MB) │ │
│ └──────────────────┘ └──────────────────┘ └───────────────┘ │
│ Tamanho final > 150MB │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Estrutura Neutralinojs (Leve) │
│ ┌────────────────────────┐ ┌──────────────────────────────┐ │
│ │ WebView Nativo do SO │ │ Seu Código │ │
│ │ (Pré-instalado) │ + │ (~2MB inicialmente) │ │
│ │ Windows: WebView2 │ │ │ │
│ │ macOS: WKWebView │ │ │ │
│ │ Linux: WebKitGTK │ │ │ │
│ └────────────────────────┘ └──────────────────────────────┘ │
│ Tamanho final ~2MB+ │
└─────────────────────────────────────────────────────────────────┘
Conceito fundamental: O Neutralinojs reutiliza o tempo de execução do WebView já integrado no sistema operacional, eliminando a necessidade de distribuir um motor de navegador completo.
2. Arquitetura de Execução
2.1 Modelo de Processsos Duplo
A aplicação é dividida em dois processos principais, separando a interface do usuário das capacidades nativas do sistema.
┌──────────────────────────────────────────────────────────────────┐
│ Ambiente de Desktop do Usuário │
│ ┌─────────────────────┐ ┌─────────────────────────────┐ │
│ │ Janela do WebView │◄──────►│ Processo do Neutralino │ │
│ │ (Camada de Interface)│ │ (Camada Nativa/Backend) │ │
│ │ │ │ │ │
│ │ • Renderização UI │ │ • Acesso ao Sistema de │ │
│ │ • Eventos DOM │ │ Arquivos │ │
│ │ • Lógica da Web │ │ • Diálogos do Sistema │ │
│ │ │ │ • APIs do SO │ │
│ └─────────────────────┘ └─────────────────────────────┘ │
│ ▲ ▲ │
│ │ Comunicação WS │ │
│ └───────────────────────────────┘ │
│ (Porta local aleatória) │
└──────────────────────────────────────────────────────────────────┘
2.2 Mecanismo de Comunicação via WebSocket
A troca de mensagens entre a camada web (frontend) e a camada nativa (backend) é realizada através de um WebSocket local.
// Código no frontend (ex: main.js)
// Esta chamada é serializada em uma mensagem para o processo nativo
const dados = await Neutralino.filesystem.readFile('/caminho/para/arquivo.txt');
// O processo subjacente ocorre da seguinte forma:
// 1. O frontend envia uma solicitação JSON.
// 2. O backend executa a operação nativa correspondente.
// 3. O resultado é retornado e a Promise é resolvida.
Formato das Mensagens:
// Solicitação
{
"id": "req_abc123",
"method": "os.showMessageBox",
"params": ["Título da Janela", "Conteúdo da mensagem", "OK", "INFO"]
}
// Resposta
{
"id": "req_abc123",
"result": "OK",
"error": null
}
3. Implementação das Capacidades Nativas
3.1 Backend em C++ com Camada de Abstração
O núcleo do Neutralinojs é escrito em C++ e compila para executáveis específicos de cada plataforma.
neutralinojs/bin/
├── neutralino-windows.exe
├── neutralino-macos
└── neutralino-linux
A arquitetura interna segue um padrão de módulos desacoplados:
┌─────────────────────────────────────────┐
│ Ponto de Entrada (main.cpp) │
└─────────────────────────────────────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌───────────────────┐
│ Servidor│ │ Adaptador │ │ Abstração de │
│ WebSocket│ │ de WebView│ │ Plataforma │
└────┬────┘ └────┬─────┘ └────────┬──────────┘
│ │ │
│ ┌───────┴───────┐ │
▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Roteador │ │Windows │ │ macOS │ │ Linux │
│ de APIs │ │(WebView2)│ │(WKWebView)│ │(WebKitGTK)│
└─────┬───┘ └─────────┘ └─────────┘ └─────────┘
│
┌───┴───┐
▼ ▼
┌─────────┐ ┌─────────┐
│ APIs de │ │ APIs de │
│Arquivo │ │ Sistema │
└─────────┘ └─────────┘
3.2 Escolha do WebView por Plataforma
| Plataforma | Componente WebView | Base Tecnológica |
|---|---|---|
| Windows | WebView2 | Microsoft Edge (Chromium) |
| macOS | WKWebView | Safari (WebKit) |
| Linux | WebKitGTK | WebKit2 |
4. Mecanismo de Carregamento de Recursos
4.1 Modo de Desenvolvimento vs. Produção
Modo de Desenvolvimento (`neu run`):
┌───────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Janela de │─────►│ Servidor Local │─────►│ Diretório resources/│
│ Preview │ │ (localhost) │ │ (Arquivos originais)│
└───────────────┘ └──────────────────┘ └─────────────────────┘
Modo de Produção (`neu build`):
┌───────────────┐ ┌───────────────────────────┐
│ Janela de │─────►│ Arquivo resources.neu │
│ Preview │ │ (Pacote de recursos ZIP) │
└───────────────┘ └───────────────────────────┘
│
▼
┌───────────────────────┐
│ Sistema de Arquivos │
│ Virtual em Memória │
└───────────────────────┘
4.2 Processo de Empacotamento
A ferramenta de linha de comando (neu) compacta o diretório resources/ em um arquivo ZIP padrão, que é renomeado para resources.neu. Durante a execução, o framework descompacta e monta esses recursos em um sistema de arquivos virtual na memória, sem a necessidade de gravar arquivos temporários no disco.
5. Modelo de Segurança
O Neutralinojs emprega um modelo de segurança baseado em permissões explícitas, ao contrário da confiança total concedida por alguns outros frameworks.
// trecho do arquivo neutralino.config.json
{
"nativeAllowList": [
"app.exit",
"filesystem.readFile",
"os.getEnv"
],
"nativeBlockList": [
"os.execCommand"
]
}
Níveis de Acesso:
┌───────────────────────────────────────────┐
│ Nível 3: Ações com Confirmação do Usuário │
│ Nível 2: Acesso ao Sistema de Arquivos │
│ Nível 1: Informações do Sistema Operacional│
│ Nível 0: Controle do Ciclo de Vida da App │
└───────────────────────────────────────────┘
No modo de produção, o servidor WebSocket vincula-se exclusivamente ao endereço de loopback (127.0.0.1), tornando-o inacessível para conexões externas.
6. Mecanismo de Extensões
Para superar as limitações do JavaScript e acessar funcionalidades de baixo nível ou de alto desempenho, o Neutralinojs suporta extensões escritas em qualquer linguagem.
┌─────────────────────────────────────────────────────────┐
│ Processo Principal do Neutralino │
│ ┌────────────────┐ ┌────────────────────────────┐│
│ │ Servidor WS │◄────►│ Gerenciador de Extensões ││
│ └───────┬────────┘ └─────────────┬──────────────┘│
│ │ │ │
│ │ ┌──────────────────────┼──────────────┐ │
│ ▼ ▼ ▼ ▼ │
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐│
│ │ Código Web │ │ Extensão │ │ Extensão ││
│ │ (JavaScript)│ │ (Python) │ │ (Rust) ││
│ └───────────────┘ └──────┬───────┘ └──────┬───────┘│
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌───────────────┐│
│ │ Biblioteca │ │ Operação ││
│ │ de IA/ML │ │ do Sistema ││
│ └──────────────┘ └───────────────┘│
└─────────────────────────────────────────────────────────┘
7. Fluxo de Inicialização
Início (execução do binário)
│
▼
┌─────────────────────────┐
│ Carregamento do binário │
│ e leitura do config.json│
└───────────┬─────────────┘
│
▼
┌─────────────────────────┐
│ Inicialização do │
│ Servidor WebSocket │
└───────────┬─────────────┘
│
▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Carregamento de Recursos│◄──────│ Criação da Janela WebView│
│ (do .neu ou do disco) │ │ e Navegação para o INDEX │
└─────────────────────────┘ └───────────┬─────────────┘
│
▼
┌───────────────────────────┐
│ Execução do Código Web │
│ (carrega neutralino.js, │
│ estabelece conexão WS) │
└───────────┬───────────────┘
│
▼
┌───────────────────────────┐
│ Evento "ready" disparado │
│ Aplicação totalmente ativa│
└───────────────────────────┘
8. Filosofia de Design Resumida
| Princípio | Implementação Concreta |
|---|---|
| Leveza Máxima | Reutilização do tempo de execução WebView do SO. |
| Zero Dependências de Terceiros | Depende apenas de bibliotecas compartilhadas presentes no sistema. |
| Interface Nativa | Utiliza componentes de UI nativos do sistema operacional. |
| Segurança por Padrão | Modelo de permissões em lista branca (whitelist). |
| Padrões Web | Não altera o comportamento do navegador; pura tecnologia web padrão. |
| Extensibilidade Multi-linguagem | Suporta extensões em qualquer linguagem através de WebSocket. |
A inovação central do Neutralinojs é ser um framework de contêiner para WebView com ponte para capacidades nativas, e não um navegador completo empacotado. Isso permite menter a experiência de desenvolvimento web com a eficiência de recursos de uma aplicação nativa.