A privacy-focused browser for iOS, based on Firefox for iOS by Mozilla.
Floorp is a community-driven project that aims to provide a customizable and privacy-respecting browsing experience. This is the iOS port of Floorp Browser.
- Xcode 26.3 (the canonical version is declared in
.xcode-version) - Node.js 24.18.1 (the canonical version is declared in
.nvmrc) - Swift Package Manager (the pinned packages are resolved by Xcode)
- SwiftLint 0.62.2 for the pre-push check (
brew install swiftlint)
Ensure xcode-select -p points to the intended Xcode installation. Mozilla's
automated FXIOS setup guide
is also useful when working with the inherited upstream toolchain.
-
Clone the repository:
git clone https://github.com/Floorp-Projects/floorp-ios.git cd floorp-ios -
Install Node.js dependencies and bootstrap:
./bootstrap.sh
-
Open
Client.xcodeprojunder thefirefox-iosfolder in Xcode. -
Select the Fennec scheme in Xcode.
-
Select a simulator (e.g. iPhone 17 Pro) and build with
Cmd + R.
- SPM dependency issues: Xcode → File → Packages → Reset Package Caches
- Build errors after upstream merge: Clean build folder (
Cmd + Shift + K) and rebuild - SwiftLint not found on push: Install it with
brew install swiftlint; do not bypass the hook for normal changes
Pull requests and pushes to main are checked by the Floorp iOS GitHub Actions workflow. It uses the pinned Xcode and Node.js versions, builds the Fennec scheme without code signing, and runs the FloorpCI baseline test plan. The main branch is protected by the Protect Floorp iOS main ruleset (pull requests with conversation resolution, required Validate workflows and Build and unit test checks, blocked force pushes and deletion). The documented contract is validated against the live ruleset by scripts/ci/check_repository_governance.py; see the governance block in docs/ci-cd.md.
The release and TestFlight foundation, current signing blockers, and Apple account setup checklist are documented in docs/ci-cd.md. Inherited Mozilla/Focus automation was removed from the active workflow directory; it remains recoverable from Git history if a Floorp-owned replacement is needed.
Execution work uses disposable task worktrees at the recorded dependency SHA; missing permissions, agreements, or approvals are recorded as exact blockers with an owner and resume condition and never reported as complete. External mutations (merges, branch/issue writes, App Store Connect, Xcode Cloud) run a read-only preflight, capture prior state, apply an idempotent mutation keyed by immutable IDs, and diff the post-state; a missing permission stops with zero mutation.
Product work proceeds through small, testable milestones beginning with Floorp Notes Local v1. See docs/roadmap.md for scope, ordering, and exit criteria.
Floorp uses WebKit's native WebExtension engine on iOS 18.4 and later. The replacement architecture is documented in docs/floorp-ios-wkwebextension-native-replacement-design.md. Release submissions that include bundled native extensions must also use the App Review notes and open-source disclosure checklist.
This repository tracks mozilla-mobile/firefox-ios as upstream. After merging upstream changes, the Floorp branding must be re-applied using the automated rebrand script.
The upstream-sync branch automation/upstream-sync is disposable: it is regenerated by the workflow, receives no manual commits, and its PR is merged by squash from the reviewed head OID only.
# 1. Fetch and merge upstream
git fetch upstream
git merge upstream/main
# 2. Resolve ordinary conflicts. The reviewed localization resolver may handle
# covered .strings conflicts; it refuses every path outside its policy.
node scripts/l10n/floorp-l10n-overlay.mjs resolve-merge --write --stage
# 3. Re-apply code, asset, and reviewed localization branding
./scripts/rebrand-to-floorp.sh
node scripts/l10n/floorp-l10n-overlay.mjs apply --source-ref upstream/main --write
node scripts/l10n/floorp-l10n-overlay.mjs verify --source-ref upstream/main
# 4. Verify the build succeeds
# 5. Commit, push a branch, and open a pull request
git add -A
git commit -m "feat: re-apply Floorp branding after upstream merge"
git push -u origin HEADscripts/rebrand-to-floorp.sh automates all Firefox → Floorp branding changes across 44 files:
| Step | Category | Description |
|---|---|---|
| 1 | Swift identifiers | Constant names (logoFirefox → logoFloorp, etc.) |
| 2 | Swift references | Usage sites across ~20 source files |
| 3 | Image set folders | xcassets .imageset directory renames (8 folders) |
| 4 | Contents.json | Image metadata filename references |
| 5 | Image files | PDF/PNG file renames |
| 6 | Swift files | File-level renames (FirefoxURLBuilding.swift → FloorpURLBuilding.swift) |
- Idempotent — already-applied changes are skipped
- Dry-run —
./scripts/rebrand-to-floorp.sh --dry-runpreviews without modifying
See ADR-0007 for the full architectural decision record.
Localized product names use a separate, reviewed overlay. It changes only 4,074 allowlisted semantic values in 849 resources, protects Mozilla service names, and fails closed when upstream text no longer matches the approved transformation. See docs/l10n-overlay.md for extraction, verification, and merge-resolution commands. Generated localization resources remain tracked so Xcode and translation tooling continue to see ordinary Apple resources.
The Upstream Sync workflow automates this process:
- Schedule: Every Monday at 09:00 UTC (18:00 JST)
- Manual trigger: Available via GitHub Actions → "Run workflow"
- Process: Fetches upstream → validates the reviewed localization policy → merges → restores Floorp-owned automation → reapplies both branding layers → opens a draft PR → dispatches CI
- Conflict handling: Protected automation is restored from Floorp; covered localization conflicts are regenerated from upstream; every other conflict aborts with a diagnostic artifact
- Generated branch:
automation/upstream-syncis replaced by each run, so fixes belong on a normal branch or in the sync tooling—not directly on the generated branch
We welcome contributions! Please feel free to submit Pull Requests or open Issues.
floorp-ios/
├── README.md # This file
├── .gitignore
├── bootstrap.sh # Project setup script
├── firefox-ios/ # Main application source
│ ├── Client/ # App code, assets, configuration
│ ├── Shared/ # Shared libraries (Strings.swift, etc.)
│ ├── WidgetKit/ # Home screen widgets
│ ├── Extensions/ # Share & Action extensions
│ └── ...
└── focus-ios/ # Focus browser (upstream, not actively modified)
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at https://mozilla.org/MPL/2.0/