Development setup

Set up your development environment for Nook Browser

This guide will help you set up your development environment to start contributing to Nook.

Initial setup

1. Clone the repository

   git clone https://github.com/nook-browser/Nook.git
   cd Nook
   
2. Switch to the dev branch

   All development work happens on the dev branch:

   git checkout dev
   
3. Open in Xcode

   open Nook.xcodeproj
   

No Swift Package Manager setup is needed. All dependencies are embedded locally in Nook/ThirdParty/.

Xcode configuration

Code signing

Before you can build and run Nook, you need to configure code signing:

1. Select the Nook target

   In Xcode, select the “Nook” target in the project navigator.

2. Configure signing

   1. Click on the “Signing & Capabilities” tab
   2. Under “Team”, select your personal Apple Developer account or team
   3. Xcode will automatically manage your signing certificates

Build scheme

Nook uses a single scheme called “Nook” for both debug and release builds:

• Debug: Select “Nook” scheme and press Cmd + R to build and run
• Release: Change the build configuration in the scheme editor

Running locally

1. Select your target

   In Xcode, select your target device/simulator from the toolbar (Mac is the default).

2. Build and run

   Press Cmd + R to build and run Nook.

The first build may take a few minutes as Xcode compiles all dependencies.

Testing

Nook includes UI tests in the NookUITests target.

Running tests in Xcode

1. Open the Test navigator

   Press Cmd + 6 or click the Test navigator icon in the left sidebar.

2. Run tests

   • Click the play button next to “NookUITests” to run all tests
   • Or click individual test methods to run specific tests

Running tests from command line

xcodebuild test -scheme Nook

Only UI tests are currently available in the NookUITests target. Unit tests are planned for future development.

Development workflow

Branch naming

Use descriptive branch names that indicate the type of work:

# Features
git checkout -b feature/add-bookmark-sync

# Bug fixes
git checkout -b fix/tab-crash-on-close

# Refactoring
git checkout -b refactor/split-browser-manager

Git workflow

All pull requests must target the dev branch, not main. This is enforced by CI.

1. Create your feature branch

   git checkout dev
   git pull origin dev
   git checkout -b feature/your-feature-name
   
2. Make your changes

   Develop your feature or fix, committing changes with clear messages.

3. Push and create PR

   git push origin feature/your-feature-name
   

   Then open a pull request targeting the dev branch on GitHub.

Getting help

If you run into issues setting up your development environment:

• Check the README for additional information
• Join our Discord to ask questions and connect with other developers
• Search existing GitHub issues for similar problems