Nativefier Deployment and Usage Guide

Prerequisites

Operating System: macOS 10.17+ / Windows / Linux
Node.js: ≥ 16.9
npm: ≥ 7.10
Optional Dependencies:
- ImageMagick or GraphicsMagick for icon conversion (ensure convert + identify or gm are in your $PATH)
- Wine to build Windows apps from non-Windows platforms (ensure wine is in your $PATH)

Installation

Global Installation (Recommended)

Install Nativefier globally using npm:

npm install -g nativefier

Alternative Installation Methods

Docker Installation

Pull the Docker image from Docker Hub:

docker pull nativefier/nativefier

Or build it yourself:

docker build -t local/nativefier .

To build an app (e.g., Gmail) into ~/nativefier-apps:

docker run --rm -v ~/nativefier-apps:/target/ nativefier/nativefier https://mail.google.com/ /target/

Snap & AUR Installation

These repositories are not managed by Nativefier maintainers. Use at your own risk.

Snap
AUR

Configuration

Nativefier doesn't require extensive configuration. However, you can customize the behavior using command-line flags. For a complete list of options, run:

nativefier --help

Key configuration options include:

--name: Set the application name
--platform: Specify target platform (win, darwin, linux)
--arch: Specify target architecture (ia32, x64, armv7l, arm64)
--icon: Use a custom icon
--inject: Inject custom CSS or JavaScript
--user-agent: Set a custom user agent

Build & Run

Basic Usage

To create a desktop app for any web page, simply run:

nativefier 'https://web.whatsapp.com/'

This will create a native-looking desktop application for WhatsApp Web.

Advanced Usage

To customize the app creation process:

nativefier --name 'My App' --platform 'win' --arch 'x64' --icon 'icon.png' 'https://example.com'

This command creates a Windows app named "My App" with a custom icon.

Development

For development purposes, you can clone the repository and work with the source code:

git clone https://github.com/nativefier/nativefier.git
cd nativefier
npm install

Deployment

Nativefier generates standalone executables that can be distributed directly. The deployment method depends on your target platform:

For Windows

Distribute the .exe file
Consider using Squirrel for automatic updates

For macOS

Distribute the .app bundle
Consider using Sparkle for automatic updates

For Linux

Distribute the executable with appropriate dependencies
Consider creating a .deb or .rpm package for easier distribution

Cross-Platform Distribution

You can use tools like Electron Forge or Electron Builder to create installers for all platforms.

Troubleshooting

Common Issues and Solutions

1. Icon Conversion Issues

Problem: Icon conversion fails with ImageMagick or GraphicsMagick.

Solution: Ensure convert and identify (ImageMagick) or gm (GraphicsMagick) are in your system PATH.

2. Windows App Building from Non-Windows Platforms

Problem: Unable to build Windows apps from macOS or Linux.

Solution: Install Wine and ensure it's in your PATH.

3. App Not Launching

Problem: The generated app fails to launch.

Solution: Check the console output for errors. Common issues include:

Missing dependencies
Network connectivity issues
Invalid target URL

4. Custom CSS/JS Injection Not Working

Problem: Injected CSS or JavaScript doesn't seem to affect the app.

Solution: Verify the file paths and ensure the files exist. Check the app's developer tools (if enabled) for any console errors.

5. Zoom Issues

Problem: Zoom functionality doesn't work as expected.

Solution: Use the built-in zoom controls or check if the web page supports zoom functionality.

Additional Resources

CATALOG.md: Site-specific ideas and workarounds contributed by the community
Issue Tracker: For reporting bugs and feature requests
API Documentation: Detailed documentation of command-line flags and options

Debug Mode

To enable debug logging, run Nativefier with the --verbose flag:

nativefier --verbose 'https://web.whatsapp.com/'

This will provide more detailed output that can help diagnose issues.

How to Deploy & Use jiahaog/nativefier