Mobile Support

EXPERIMENTAL

Mobile support in Wails v3 is currently EXPERIMENTAL. The API and build process may change significantly before the final release. Use at your own risk in production environments.

Wails v3 introduces experimental support for building native mobile applications for iOS and Android platforms. This allows you to use the same Go codebase and web frontend across desktop and mobile platforms.

Overview

Mobile support enables you to build native iOS and Android applications using:

• Go for business logic and services
• Web technologies (HTML/CSS/JavaScript) for the UI
• Native WebView components for rendering

Architecture

Platform	WebView	Bridge Technology	Build Output
iOS	WKWebView	CGO (C headers)	.app / .ipa
Android	Android WebView	JNI	.apk

Prerequisites

iOS Development

macOS Required

iOS development requires macOS with Xcode installed.

• macOS 12.0 or later
• Xcode 14.0 or later
• Go 1.21+ with CGO support
• iOS SDK (included with Xcode)

Android Development

Android development is supported on macOS, Linux, and Windows.

Required Components:

• Go 1.21+ with CGO support
• Android SDK with:
  • Platform Tools (adb)
  • Build Tools
  • Android Emulator (optional, for testing)
• Android NDK r26d or later
• Java JDK 11+

Environment Setup

Android Environment Variables

Add these to your shell profile (~/.bashrc, ~/.zshrc, etc.):

# macOS
export ANDROID_HOME="$HOME/Library/Android/sdk"

# Linux
export ANDROID_HOME="$HOME/Android/Sdk"

# NDK (adjust version as needed)
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/29.0.14206865"

# Add tools to PATH
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

Installing Android SDK

You can install the Android SDK through:

• Android Studio (easiest method - includes all tools)
• Command line tools from developer.android.com

After installing, use SDK Manager to install:

• Android SDK Platform (API 34 or later)
• Android SDK Build-Tools
• Android NDK (if not already included)

Building for Mobile

iOS Build

# Build for iOS
task ios:build

# Build and run on simulator
task ios:run

# Build for device (requires code signing)
task ios:build:device

The build process will:

1. Compile Go code as a static library (.a file)
2. Generate Xcode project
3. Build the app using xcodebuild
4. Create an .app bundle (or .ipa for distribution)

Android Build

# Build for Android (default: arm64 for device)
task android:build

# Build for emulator (x86_64)
task android:build ARCH=x86_64

# Build for all architectures
task android:compile:go:all-archs

# Package APK
task android:package

# Run on emulator/device
task android:run

# View logs
task android:logs

The build process will:

1. Compile Go code as a shared library (.so file)
2. Build Java/Kotlin code using Gradle
3. Package everything into an APK

Build Architectures

iOS:

• arm64 - iPhone 5s and later, all iPads with Apple Silicon

Android: | Architecture | Use Case | GOARCH | |--------------|----------|---------| | arm64-v8a | Modern devices (most common) | arm64 | | x86_64 | Emulator | amd64 | | armeabi-v7a | Older devices (optional) | arm | | x86 | Older emulators (optional) | 386 |

Platform-Specific Configuration

iOS Options

app := application.New(application.Options{
    Name: "My App",
    iOS: application.IOSOptions{
        // Disable bounce scroll effect
        DisableBounce: true,

        // Enable zoom gestures
        EnableZoom: false,

        // Custom user agent
        UserAgent: "MyApp/1.0",

        // Background color
        BackgroundColour: application.NewRGB(255, 255, 255),
    },
})

Android Options

app := application.New(application.Options{
    Name: "My App",
    Android: application.AndroidOptions{
        // Disable scrolling
        DisableScroll: false,

        // Disable overscroll bounce effect
        DisableOverscroll: true,

        // Enable pinch-to-zoom
        EnableZoom: false,

        // Custom user agent
        UserAgent: "MyApp/1.0",

        // Background color
        BackgroundColour: application.NewRGB(255, 255, 255),

        // Disable hardware acceleration (not recommended)
        DisableHardwareAcceleration: false,
    },
})

Testing

iOS Testing

# List available simulators
xcrun simctl list devices

# Run on specific simulator
task ios:run SIMULATOR="iPhone 15 Pro"

Android Testing

# List available emulators
emulator -list-avds

# Start emulator
emulator -avd Pixel_7_API_34

# Install and run
task android:run

Platform Detection

Your frontend JavaScript can detect the platform:

const platform = window.wails.System.Platform();

if (platform === 'ios') {
    // iOS-specific code
} else if (platform === 'android') {
    // Android-specific code
} else {
    // Desktop code
}

Limitations

Current Limitations

The following features are not yet fully implemented on mobile platforms:

iOS Limitations

• System tray/menu bar (not applicable)
• Multiple windows (single full-screen window only)
• File dialogs (limited by iOS sandboxing)
• Window manipulation (position, size, etc.)

Android Limitations

• System tray (not applicable)
• Multiple windows (single full-screen window only)
• File dialogs (use Storage Access Framework)
• Window manipulation (fullscreen only)
• Clipboard operations (partial support)

Architecture Documentation

For detailed technical information about the mobile implementations:

• Android Architecture: See ANDROID_ARCHITECTURE.md in the repository
• iOS Architecture: See IOS_ARCHITECTURE.md in the repository

These documents provide comprehensive information about:

• Architecture and design patterns
• Build system internals
• Bridge implementations (JNI for Android, CGO for iOS)
• Asset serving mechanisms
• JavaScript bridge details
• Security considerations

Troubleshooting

iOS Issues

"Code signing required"

• You need an Apple Developer account to run on physical devices
• Simulators don't require code signing

"Command Line Tools not found"

# Install Xcode Command Line Tools
xcode-select --install

Android Issues

"NDK not found"

# Verify NDK installation
ls $ANDROID_HOME/ndk

# Set NDK path explicitly
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/26.1.10909125

"UnsatisfiedLinkError: dlopen failed"

• Architecture mismatch between Go library and device
• Rebuild for correct architecture (arm64 for device, x86_64 for emulator)

Blank WebView

1. Enable WebView debugging (in development builds)
2. Use Chrome DevTools: chrome://inspect/#devices
3. Check asset serving in logcat: task android:logs

Build Issues

"cannot find package"

# Clear and rebuild Go modules
go clean -modcache
go mod tidy
go mod download

"CGO_ENABLED required"

# Ensure CGO is enabled
export CGO_ENABLED=1

Examples

Check out the example projects in the Wails repository:

• iOS Example: v3/examples/ios/
• Android Example: v3/examples/android/

These examples demonstrate:

• Basic app structure
• Service integration
• Event handling
• Asset serving
• Platform-specific features

Getting Help

If you encounter issues with mobile support:

1. Check the GitHub Issues for known problems
2. Review the architecture documentation linked above
3. Ask in the Wails Discord #mobile channel
4. Report bugs with detailed logs and environment information

Feedback Welcome

Mobile support is actively being developed. Your feedback and bug reports are valuable for improving the implementation. Please share your experiences on GitHub or Discord!