NW.js Advanced Builder

Powerful and flexible builder for NW.js applications with multi-platform support

Features • Installation • Quick Start • Documentation • Examples

📋 Overview

NW.js Advanced Builder (NWAB) is a comprehensive TypeScript-based build tool for creating distributable NW.js applications. It simplifies the process of packaging your web applications into native desktop apps for Windows, Linux, and macOS with support for multiple architectures.

✨ Features

• 🚀 Multi-platform support - Build for Windows, Linux, and macOS simultaneously
• 🏗️ Multi-architecture - Support for ia32, x64, and arm64 architectures
• 📦 Automatic binary management - Downloads and caches NW.js binaries automatically
• 🎨 Platform-specific configuration - Customize icons, metadata, and settings per platform
• 🔧 FFmpeg support - Optional FFmpeg integration for media playback
• ⚡ Vite plugin - Seamless integration with Vite for modern web development
• 🎯 Dev mode - Hot reload and development workflow support
• 📝 TypeScript - Fully typed with comprehensive type definitions
• 🔄 Smart caching - Efficient caching system to avoid redundant downloads

📦 Installation

# Using pnpm (recommended)
pnpm add -D nw-advenced-builder

# Using npm
npm install --save-dev nw-advenced-builder

# Using yarn
yarn add -D nw-advenced-builder

🚀 Quick Start

Basic Usage

import NWAB from 'nw-advenced-builder';

const builder = new NWAB({
  nwjs: {
    version: '0.72.0',
    platforms: ['win', 'linux', 'osx'],
    arch: ['x64'],
    ffmpeg: true,
  },
  app: {
    name: 'my-app',
    version: '1.0.0',
    directory: './dist',
    output: './builds',
    icon: './assets/icon.ico',
  },
});

// Development mode
await builder.run('dev');

// Production build
await builder.run('build');

With Vite

// vite.config.ts
import { defineConfig } from 'vite';
import vitePluginNWAB from 'nw-advenced-builder/vite';

export default defineConfig({
  plugins: [
    vitePluginNWAB({
      nwjs: {
        version: '0.72.0',
        platforms: ['win', 'linux', 'osx'],
        arch: ['x64'],
      },
      app: {
        name: 'my-app',
        version: '1.0.0',
        directory: './dist',
        output: './builds',
        icon: './assets/icon.ico',
      },
    }),
  ],
});

📚 Documentation

Configuration Options

nwjs Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | version | string | 'latest' | NW.js version to use (e.g., '0.72.0', 'latest', 'stable', 'lts') | | platforms | NWPlatform[] | ['win', 'linux', 'osx'] | Target platforms | | arch | NWArch[] | ['ia32', 'x64'] | Target architectures | | ffmpeg | boolean | false | Enable FFmpeg support | | flavor | 'normal' \| 'sdk' | 'normal' | NW.js flavor (normal or SDK) | | platformSettings | object | {} | Platform-specific overrides |

app Configuration

| Option | Type | Required | Description | |--------|------|---------|-------------| | name | string | ✅ | Application name | | directory | string | ✅ | Source directory containing your app | | output | string | ✅ | Output directory for builds | | version | string | ❌ | Application version | | icon | string | ❌ | Path to application icon | | cache | string | ❌ | Cache directory (default: './cache') | | zip | boolean | ❌ | Create ZIP archives of builds |

Advanced Configuration

Platform-Specific Settings

const builder = new NWAB({
  nwjs: {
    version: '0.72.0',
    platforms: ['win', 'linux', 'osx'],
    arch: ['x64', 'arm64'],
    platformSettings: {
      win: {
        arch: ['x64'], // Only x64 for Windows
        version: '0.72.0',
      },
      linux: {
        arch: ['x64'],
      },
      osx: {
        version: '0.62.2', // Different version for macOS
        arch: ['x64', 'arm64'], // Support both Intel and Apple Silicon
      },
    },
  },
  app: {
    name: 'my-app',
    directory: './dist',
    output: './builds',
    settings: {
      win: {
        icon: './icons/icon.ico',
        properties: {
          FileDescription: 'My Awesome App',
          ProductName: 'My App',
          CompanyName: 'My Company',
        },
      },
      linux: {
        icon: './icons/icon.png',
        properties: {
          Name: 'My App',
          Comment: 'My Awesome Application',
          Categories: 'Utility;',
        },
      },
      osx: {
        icon: './icons/icon.icns',
      },
    },
  },
});

💡 Examples

Development Mode

Development mode automatically downloads the SDK version of NW.js and launches your application:

const builder = new NWAB({
  nwjs: {
    version: '0.72.0',
    platforms: ['win'],
    arch: ['x64'],
    flavor: 'sdk', // SDK flavor for development
  },
  app: {
    name: 'my-app',
    directory: './src',
    output: './dist',
  },
});

// Launch in development mode
await builder.run('dev');

Production Build

Build distributable packages for multiple platforms:

const builder = new NWAB({
  nwjs: {
    version: '0.72.0',
    platforms: ['win', 'linux', 'osx'],
    arch: ['x64'],
    ffmpeg: true,
  },
  app: {
    name: 'my-app',
    version: '1.0.0',
    directory: './dist',
    output: './builds',
    icon: './assets/icon.ico',
    zip: true, // Create ZIP archives
  },
});

// Build for all platforms
await builder.run('build');

Custom Manifest URLs

Use custom repositories for NW.js binaries:

const builder = new NWAB({
  nwjs: {
    version: '0.72.0',
    platforms: ['win'],
    arch: ['x64'],
    buildsRepoUrl: 'https://dl.nwjs.io',
    manifestRepoUrl: 'https://nwjs.io/versions.json',
    ffmpegRepoUrl: 'https://github.com/nwjs-ffmpeg-prebuilt/nwjs-ffmpeg-prebuilt/releases/download',
  },
  app: {
    name: 'my-app',
    directory: './dist',
    output: './builds',
  },
});

🔌 Vite Integration

The Vite plugin automatically handles development and production builds:

// vite.config.ts
import { defineConfig } from 'vite';
import vitePluginNWAB from 'nw-advenced-builder/vite';

export default defineConfig({
  plugins: [
    vitePluginNWAB({
      nwjs: {
        version: '0.72.0',
        platforms: ['win', 'linux', 'osx'],
        arch: ['x64'],
      },
      app: {
        name: 'my-app',
        version: '1.0.0',
        directory: './dist',
        output: './builds',
        icon: './assets/icon.ico',
      },
    }),
  ],
  build: {
    outDir: './dist',
  },
});

Development: The plugin automatically launches NW.js when the dev server starts.

Production: The plugin automatically builds distributable packages after Vite build completes.

🛠️ API Reference

NWAB Class

Constructor

new NWAB(config: NWABConfig)

Methods

run(mode?: 'dev' | 'build'): Promise<void>

Run the builder in the specified mode.

• mode: 'dev' - Development mode (default)
• mode: 'build' - Production build mode

dev(): Promise<void>

Launch the application in development mode.

build(): Promise<void>

Build distributable packages for all configured platforms.

verifyCache(mode: RunMode): Promise<void>

Verify and download required NW.js binaries.

📝 Type Definitions

All types are exported for TypeScript projects:

import type {
  NWABConfig,
  NWPlatform,
  NWArch,
  NWFlavor,
  NWPropertiesWin,
  NWPropertiesLinux,
} from 'nw-advenced-builder';

🐛 Troubleshooting

Manifest Parsing Errors

If you encounter manifest parsing errors, delete the cache directory:

rm -rf ./cache

The builder will automatically re-download and fix the manifest.

Platform-Specific Issues

• Windows: Ensure you have proper icon files (.ico) and metadata
• Linux: Desktop file properties are required for proper integration
• macOS: Icon files should be in .icns format

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

This project uses Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes
• refactor: - Code refactoring
• test: - Test additions/changes
• chore: - Build process or auxiliary tool changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NW.js - The framework that makes this possible
• All contributors and users of this project

📮 Support

• 🐛 Report a Bug
• 💡 Request a Feature
• 📧 Contact

Made with ❤️ by DNTZ