Elixir Desktop

To transform an existing Phoenix application into a desktop application using elixir-desktop, follow these steps:

1. Add the dependency: Add {:desktop, github: "elixir-desktop/desktop"} to your mix.exs.
2. Update the Endpoint:
   • Change your endpoint module to use Desktop.Endpoint instead of Phoenix.Endpoint.
   • Add plug Desktop.Auth to the endpoint pipeline to restrict access to the Desktop app's WebView.
3. Configure the Endpoint: Set the http port to 0 (to allow automatic port selection) and ensure server: true is set in your configuration (config/dev.exs or config/runtime.exs).
4. Add the Window specification: Add {Desktop.Window, [app: :your_app, id: DemoWindow, url: &YourWeb.Endpoint.url/0]} to your application's supervision tree.

# 1. mix.exs
defp deps do
  [
    {:desktop, github: "elixir-desktop/desktop"}
  ]
end

# 2. Endpoint configuration
defmodule DemoWeb.Endpoint do
  use Desktop.Endpoint, otp_app: :demo
  plug Desktop.Auth
  # ...
end

# 3. Application supervision tree
defmodule Demo.Application do
  def start(_type, _args) do
    children = [
      DemoWeb.Endpoint,
      {
        Desktop.Window,
        [
          app: :demo,
          id: DemoWindow,
          url: &DemoWeb.Endpoint.url/0
        ]
      }
    ]
    # ...
  end
end

# 4. config/dev.exs
config :demo, DemoWeb.Endpoint,
  http: [ip: {127, 0, 0, 1}, port: 0],
  server: true

All UI operations in elixir-desktop are delegated to a single backend module via Desktop.Platform. You can select a backend automatically or explicitly via configuration.

Automatic Selection

By default (config :desktop, :backend, :auto), the library selects a backend based on the following priority:

1. Mobile: If config :desktop, :mobile_target, true is set at compile time or Desktop.OS.mobile?/0 returns true (via ELIXIR_DESKTOP_OS), it uses Desktop.Backend.Json.
2. No wxWidgets: If the NO_WX environment variable is set or OTP :wx is unavailable, it uses Desktop.Backend.Browser.
3. Default: Otherwise, it uses Desktop.Backend.Wx.

Explicit Configuration

You can force a specific backend in your config/config.exs:

• :wx: Native wxWidgets window + webview.
• :json: JSON/TCP bridge (used for mobile native hosts).
• :browser: Opens URLs in the OS default browser; no native window is created.
• Custom: Provide a module that implements the Desktop.Platform.Window, Content, Notification, Media, System, and Menu behaviours.

Note: You must restart the application after changing backend configuration.

# Explicitly setting the backend in config/config.exs
config :desktop, :backend, :wx      # native wxWidgets window + webview
config :desktop, :backend, :json    # JSON/TCP bridge (mobile native host)
config :desktop, :backend, :browser # OS default browser, no native window

# Custom backend implementation
config :desktop, :backend, MyApp.DesktopBackend

Elixir Desktop uses msys2 on Windows to produce native applications. Follow these steps:

1. Install Erlang 24: Download from erlang.org or build from source.
2. Install msys2: Download from msys2.org.
3. Install msys2 dependencies: Open an msys2 64-bit shell and run the pacman commands provided below.
4. Install Elixir 1.12+: Download the precompiled zip and add the bin directory to your PATH via .bashrc.
5. Install Node.js: Get npm and Node 12.x (or higher) from nodejs.org and add the binary path to your msys2 PATH.
6. Install NSIS: Required for building installers. Get it from nsis.sourceforge.io.

# Install msys2 packages in an msys2 64-bit shell
pacman -Syu
pacman -S --noconfirm pacman-mirrors pkg-config
pacman -S --noconfirm --needed base-devel autoconf automake make libtool mingw-w64-x86_64-toolchain mingw-w64-x86_64-openssl mingw-w64-x86_64-libtool git

# Install Elixir 1.12+ in an msys2 64-bit shell
mkdir $HOME/elixir && cd $HOME/elixir
wget https://github.com/elixir-lang/elixir/releases/download/v1.12/Precompiled.zip
unzip Precompiled.zip
echo "export PATH=\"$HOME/elixir/bin:\$PATH\"" >> ~/.bashrc
export PATH="$HOME/elixir/bin:$PATH"

1. Install Elixir: Use Homebrew to install Elixir, which will also fetch Erlang.

   brew install elixir

2. Install Xcode Command Line Tools: Required for building NIFs and packaging releases. Open Xcode -> Preferences -> General -> Downloads -> Components and install Command Line Tools.
3. Install Node.js/npm: Use nvm to install version 12.16.1.

   brew install nvm
   nvm install v12.16.1

Using custom wxWidgets (Advanced)

If you encounter visual issues with native Menus or Taskbar Icons, you can build a custom version of wxWidgets from the master branch and rebuild Erlang using kerl with the --with-wxdir flag.

# Install Node via nvm
brew install nvm
nvm install v12.16.1

# Example: Building custom wxWidgets
git clone https://github.com/wxWidgets/wxWidgets.git
cd wxWidgets
git checkout master
./configure --prefix=/usr/local/wxWidgets --enable-clipboard --enable-controls \
      --enable-dataviewctrl --enable-display \
      --enable-dnd --enable-graphics_ctx \
      --enable-std_string --enable-svg \
      --enable-unicode --enable-webview \
      --with-expat --with-libjpeg \
      --with-libpng --with-libtiff \
      --with-opengl --with-zlib \
      --disable-precomp-headers --disable-monolithic

make -j4