This guide will help you set up your development environment to start contributing to Nook.
Initial setup
Clone the repository
git clone https://github.com/nook-browser/Nook.git
cd Nook
Switch to the dev branch
All development work happens on the dev branch: 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:
Select the Nook target
In Xcode, select the “Nook” target in the project navigator.
Configure signing
- Click on the “Signing & Capabilities” tab
- Under “Team”, select your personal Apple Developer account or team
- 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
Select your target
In Xcode, select your target device/simulator from the toolbar (Mac is the default).
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
Open the Test navigator
Press Cmd + 6 or click the Test navigator icon in the left sidebar.
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.
Create your feature branch
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name
Make your changes
Develop your feature or fix, committing changes with clear messages.
Push and create PR
git push origin feature/your-feature-name
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