Skip to main content
Ora Browser is built natively for macOS using Swift and SwiftUI. Follow these steps to get started with development or build the app from source.
Ora is currently in early stages of development and not yet ready for day-to-day use. A beta version with core functionalities will be released soon.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

macOS 14.0+

macOS Sonoma or later

Xcode 15+

Xcode 15 or later with Swift 5.9

Homebrew

Package manager for macOS

Command Line Tools

Xcode Command Line Tools

​
Install Homebrew

If you don’t have Homebrew installed, install it first: 
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

​
Install Xcode

Download and install Xcode from the Mac App Store or Apple Developer.

​
Installation Steps

1

Clone the Repository

Clone the Ora Browser repository from GitHub:
git clone https://github.com/the-ora/browser.git
cd browser
2

Run Setup Script

The setup script will install required development tools and configure your environment:
./scripts/setup.sh
This script will:
  • Install XcodeGen for project file generation
  • Install SwiftFormat and SwiftLint for code quality
  • Install xcbeautify for better build output
  • Install Lefthook for git hooks
  • Set up git hooks automatically
  • Generate the Xcode project file (Ora.xcodeproj)
The script checks for existing installations and only installs missing dependencies.
3

Open in Xcode

Open the generated Xcode project:
open Ora.xcodeproj
Wait for Xcode to resolve Swift Package Manager dependencies. This may take a few minutes on first launch.
4

Select Scheme and Build

In Xcode:
  1. Select the ora scheme from the scheme dropdown
  2. Choose your Mac as the destination
  3. Build and run the app using ⌘R or Product → Run
The first build may take several minutes as Xcode compiles all dependencies.

​
Build Configurations

Ora Browser has two build configurations:

​
Debug Build

  • Uses development icon (OraIconDev)
  • Includes hot reloading support via InjectionIII
  • Enables developer-friendly compiler flags
  • Uses debug entitlements (ora-debug.entitlements)

​
Release Build

  • Uses production icon (OraIcon)
  • Optimized for performance
  • Production entitlements (ora.entitlements)
  • Ready for distribution

​
Project Dependencies

Ora Browser uses the following Swift packages: 
URL: https://github.com/sparkle-project/Sparkle
Version: 2.6.0+
Purpose: Automatic app updates

​
Development Tools

The following tools are automatically installed by the setup script:
ToolPurposeCommand
XcodeGenGenerates Xcode project from project.ymlxcodegen
SwiftFormatAutomatic code formattingswiftformat . --quiet
SwiftLintSwift code lintingswiftlint --quiet
xcbeautifyBeautifies Xcode build outputUsed in CI/CD
LefthookGit hooks managerlefthook install

​
Hot Reloading (Optional)

For faster development with live UI updates, set up InjectionIII:
1

Install InjectionIII

Download from the Mac App Store
2

Configure InjectionIII

  1. Launch InjectionIII
  2. Click Open Project from the menu bar icon
  3. Select your browser folder
3

Run in Debug Mode

Build and run from Xcode. You should see a green status in the InjectionIII menu bar icon.
4

Make Changes

Edit any Swift file and save—changes appear instantly without rebuilding!
Hot reloading only works in Debug builds and has zero impact on Release builds.

​
Running Tests

​
From Xcode

Press ⌘U or go to Product → Test

​
From Command Line

xcodebuild test -scheme ora -destination "platform=macOS"

​
Regenerating the Xcode Project

If you need to modify project settings, edit project.yml and regenerate: 
xcodegen
Never modify Ora.xcodeproj directly. All project configuration should be done in project.yml.

​
Troubleshooting

​
Build Failures

If you encounter build errors:
  1. Clean build folder: Product → Clean Build Folder (⇧⌘K)
  2. Reset package cache: File → Packages → Reset Package Caches
  3. Regenerate project: Run xcodegen again
  4. Restart Xcode: Sometimes a full restart is needed

​
Missing Dependencies

If setup script fails to install dependencies: 
# Install manually via Homebrew
brew install xcodegen swiftlint swiftformat xcbeautify lefthook

​
Git Hooks Not Working

Reinstall git hooks: 
lefthook install

​
Signing Issues

For development, use Automatic code signing in Xcode:
  1. Select the ora target
  2. Go to Signing & Capabilities
  3. Set “Automatically manage signing” to enabled
  4. Select your Apple Developer team

​
Next Steps

Quick Start

Learn how to use Ora Browser

Contributing

Contribute to Ora Browser

Build docs developers (and LLMs) love

Get started for freeTalk to us