node-windows-forms

Легковесная Node.js обертка для нативных Windows Forms. Создавайте молниеносно быстрые нативные десктопные интерфейсы Windows прямо из Node.js с минимальным потреблением ресурсов.

Почему node-windows-forms?

Если вы хотите написать десктопное приложение на Node.js, обычно ваш выбор — Electron. Но Electron тянет за собой целый браузер Chromium, из-за чего даже самое простое приложение "Hello World" потребляет 100+ МБ оперативной памяти и занимает сотни мегабайт на диске.

node-windows-forms решает эту проблему, используя изолированный C# хост, общающийся через IPC (межпроцессное взаимодействие).

• Легковесность: Потребляет всего ~30 МБ памяти.
• Нативный UX (интерфейс): Доступ к реальным нативным компонентам Windows (Системный трей, MessageBox, DataGridView и др.).
• Надежная архитектура: Node.js общается с уже скомпилированным C# .exe через именованные пайпы (Named Pipes). Никаких хрупких C++ модулей (native addons), которые ломаются при каждом обновлении Node.js!
• Zero Config: C# хост заранее скомпилирован в крошечный исполняемый файл. Просто напишите npm install и всё готово.

Установка

npm install node-windows-forms

Примечание: Пакет включает в себя прекомпилированный .NET 10 Framework бинарник. Если у пользователя не установлен .NET Desktop Runtime, Windows безопасно предложит ему скачать его с официального сайта Microsoft при первом запуске.

Быстрый старт (Hello World)

const { WinFormsSession, Form, Button, MessageBox } = require('node-windows-forms');

async function main() {
    // 1. Инициализируем сессию
    const session = new WinFormsSession();
    await session.start();

    // 2. Создаем Окно (Form)
    const form = new Form(session);
    form.Text = "Мое первое приложение";
    form.Width = 300;
    form.Height = 200;

    // 3. Создаем Кнопку
    const btn = new Button(session, form);
    btn.Text = "Нажми меня!";
    btn.Width = 100;
    btn.Height = 40;
    btn.Left = 90;
    btn.Top = 50;

    // 4. Слушаем события
    btn.OnClick.Attach(() => {
        MessageBox.show(session, "Привет из Node.js!", "Успех", "OK", "Information");
    });

    // 5. Показываем окно
    await form.show();
}

main().catch(console.error);

Возможности (Контролы)

• Стандартные: Form, Button, TextBox, Label, ComboBox, CheckBox, Panel, FlowLayoutPanel, ListBox, PictureBox, ProgressBar, TabControl.
• Продвинутые: DataGridView (Таблицы с двусторонним доступом к данным), MenuStrip, ContextMenuStrip.
• Системный Трей: NotifyIcon позволяет вашим Node.js приложениям тихо работать в панели задач (возле часов).
• Нативные Диалоги: MessageBox, OpenFileDialog, SaveFileDialog, FolderBrowserDialog.

Пример приложения в трее

const { WinFormsSession, NotifyIcon, ContextMenuStrip } = require('node-windows-forms');

async function run() {
    const session = new WinFormsSession();
    await session.start();

    // Создаем иконку в трее
    const trayIcon = new NotifyIcon(session);
    trayIcon.Text = "Мое Node.js Приложение";
    trayIcon.Icon = "default"; 
    trayIcon.Visible = true;

    // Добавляем меню по правому клику
    const contextMenu = new ContextMenuStrip(session);
    const exitItem = contextMenu.addMenuItem("Выход");
    
    exitItem.OnClick.Attach(() => {
        trayIcon.Visible = false;
        session.stop();
        process.exit(0);
    });

    trayIcon.ContextMenuStrip = contextMenu.id;
}

run();

Сборка в один исполняемый файл (.exe)

Вы можете скомпилировать ваше Node.js приложение в один нативный файл .exe используя встроенную CLI утилиту. Итоговый файл является полностью самостоятельным (standalone) и содержит внутри себя среду выполнения Node.js и ваш скрипт. Вы также можете задать собственное имя процессу и иконку приложению:

npx nwf-build app.js -o MyApp.exe -i icon.ico

Опции:

• -o, --output : Имя выходного исполняемого файла.
• -i, --icon : Путь к файлу .ico, который будет установлен в качестве иконки приложения.

Сборщик использует нативный механизм Node.js SEA (Single Executable Applications) в связке с кастомным патчером PE-заголовков. Это означает, что вам больше не нужны сторонние архиваторы и упаковщики.

Режим присоединения (Attach Mode / Visual Studio)

Вы можете собрать визуальный интерфейс в Visual Studio с помощью визуального дизайнера (Windows Forms Designer) и затем подключить к нему управляющую логику на Node.js. Для этого вашему C# проекту потребуется доступ к классам IPC-хоста.

1. Добавьте необходимые файлы библиотеки в ваш C# проект. Это можно сделать, подключив папки src/Core/ и src/IPC/ в вашем файле .csproj:

   <ItemGroup>
     <Compile Include="путь\к\node-windows-forms\src\Core\**\*.cs" Link="Core\%(RecursiveDir)%(Filename)%(Extension)" />
     <Compile Include="путь\к\node-windows-forms\src\IPC\**\*.cs" Link="IPC\%(RecursiveDir)%(Filename)%(Extension)" />
   </ItemGroup>

2. В вашем C# проекте запустите IPC-хост с заранее заданным именем канала (pipe), вместо того чтобы Node запускал новый процесс:

   // Program.cs
   var host = new NodeWindowsForms.Core.IpcHost(mainForm, "MyCustomPipeName", isSpawnMode: false);
   host.StartLoop();
   Application.Run(mainForm);

3. Запустите ваше скомпилированное C# приложение (например, из Visual Studio).
4. В Node.js подключитесь к уже запущенному C# приложению по тому же имени канала:

   const session = new WinFormsSession({ pipeName: 'MyCustomPipeName' });
   const controls = await session.start();
      
   // Получаем доступ к компонентам, заранее созданным в дизайнере Visual Studio
   controls.Form1.Text = "Управляется из Node.js!";

Как это работает под капотом

1. Когда вы вызываете new WinFormsSession().start(), Node.js запускает легковесное, прекомпилированное C# приложение (node-windows-forms.exe). (При использовании nwf-build, этот бинарник кодируется в base64 и "вшивается" напрямую в ваш итоговый .exe, а при запуске автоматически распаковывается во временную папку ОС).
2. Node.js генерирует уникальный Named Pipe (именованный канал) и передает его в C# процесс.
3. Node.js отправляет JSON-команды через этот канал для создания компонентов ({"action": "create", "type": "Button", ...}).
4. C# процесс моментально отрисовывает настоящие нативные WinForms компоненты.
5. Когда пользователь нажимает кнопку, C# отправляет JSON-событие обратно в Node.js.

Лицензия

ISC License.

🇬🇧 English version: README.md