Repository: Ranchero-Software/NetNewsWire
Stars: 9933
CLAUDE.md
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Build and Development Commands
Building and Testing
- Full build and test:
./buildscripts/build_and_test.sh - Builds both macOS and iOS targets and runs all tests- Quiet build and test:
./buildscripts/quiet_build_and_test.sh - Same as above with less verbose output- Manual Xcode builds:
- macOS:
xcodebuild -project NetNewsWire.xcodeproj -scheme NetNewsWire -destination "platform=macOS,arch=arm64" build- iOS:
xcodebuild -project NetNewsWire.xcodeproj -scheme NetNewsWire-iOS -destination "platform=iOS Simulator,name=iPhone 17" buildTesting
- Run all tests: Use the
NetNewsWire.xctestplan which includes tests from all modules- Individual test runs follow same xcodebuild pattern with
test action instead of buildSetup
- First-time setup: Run
./setup.sh to configure development environment and code signing- Manual setup: Create
SharedXcodeSettings/DeveloperSettings.xcconfig in parent directoryProject Architecture
High-Level Structure
NetNewsWire is a multi-platform RSS reader with separate targets for macOS and iOS, organized as a modular architecture with shared business logic.
Key Modules (in /Modules)
- RSCore: Core utilities, extensions, and shared infrastructure
- RSParser: Feed parsing (RSS, Atom, JSON Feed, RSS-in-JSON)
- RSWeb: HTTP networking, downloading, caching, and web services
- RSDatabase: SQLite database abstraction layer using FMDB
- Account: Account management (Local, Feedbin, Feedly, NewsBlur, Reader API, CloudKit)
- Articles: Article and author data models
- ArticlesDatabase: Article storage and search functionality
- SyncDatabase: Cross-device synchronization state management
- Secrets: Secure credential and API key management
Platform-Specific Code
- Mac/: macOS-specific UI (AppKit), preferences, main window management
- iOS/: iOS-specific UI (UIKit), settings, navigation
- Shared/: Cross-platform business logic, article rendering, smart feeds
Key Architectural Patterns
- Account System: Pluggable account delegates for different sync services
- Feed Management: Hierarchical folder/feed organization with OPML import/export
- Article Rendering: Template-based HTML rendering with custom CSS themes
- Smart Feeds: Virtual feeds (Today, All Unread, Starred) implemented as PseudoFeed protocol
- Timeline/Detail: Classic three-pane interface (sidebar, timeline, detail)
Extension Points
- Share extensions for both platforms
- Safari extension for feed subscription
- Widget support for iOS
- AppleScript support on macOS
- Intent extensions for Siri shortcuts
Development Notes
- Uses Xcode project with Swift Package Manager for module dependencies
- Requires
xcbeautify for formatted build output in scripts- API keys are managed through buildscripts/updateSecrets.sh (runs during builds)
- Some features disabled in development builds due to private API keys
- Code signing configured through SharedXcodeSettings for development
- Documentation and technical notes are located in the
Technotes/ folderCode Formatting
Prefer idiomatic modern Swift.
Prefer if let x and guard let x over if let x = x and guard let x = x.
Don’t use ... or … in Logger messages.
Guard statements should always put the return in a separate line.
Don’t do force unwrapping of optionals.
Things to Know
Just because unit tests pass doesn’t mean a given bug is fixed. It may not have a test. It may not even be testable — it may require manual testing.
README.md
<img src=Technotes/Images/icon_1024.png height=128 width=128 style="display: block; margin: auto;">
NetNewsWire
NetNewsWire is a free and open-source feed reader for macOS and iOS.
It supports RSS, Atom, JSON Feed, and RSS-in-JSON formats.
More info: https://netnewswire.com/
You can report bugs and make feature requests here on GitHub. You can also read change notes for current and previous releases.
Here’s How to Support NetNewsWire. Spoiler: don’t send money. :)
(NetNewsWire’s Help menu has these links, so you don’t have to remember to come back to this page.)
#### Community
Join the forum to talk with other NetNewsWire users — and to help out, if you’d like to, by testing, coding, writing, providing feedback, or just helping us think things through. Everybody is welcome and encouraged to join.
Every community member is expected to abide by the code of conduct which is included in the Contributing page.
#### Pull Requests
See the Contributing page for our process. They key thing is to ask before doing a PR (before even starting work). The Contributing page goes into more detail as to why it’s important to ask first.
#### Building
You can build and test NetNewsWire without a paid developer account.
git clone https://github.com/Ranchero-Software/NetNewsWire.gitYou can locally override the Xcode settings for code signing
by creating a DeveloperSettings.xcconfig file locally at the appropriate path.
This allows for a pristine project with code signing set up with the appropriate
developer ID and certificates, and for developer to be able to have local settings
without needing to check in anything into source control.
You can do this in one of two ways: using the included setup.sh script or by creating the folder structure and file manually.
##### Using setup.sh
- Open Terminal and cd into the NetNewsWire directory.
- Run this command to ensure you have execution rights for the script: chmod +x setup.sh
- Execute the script with the following command: ./setup.sh and complete the answers.
##### Manually
Make a directory SharedXcodeSettings next to where you have this repository.
The directory structure is:
directory/
SharedXcodeSettings/
DeveloperSettings.xcconfig
NetNewsWire/
NetNewsWire.xcodeprojExample:
If your NetNewsWire Xcode project file is at:/Users/name/projects/NetNewsWire/NetNewsWire.xcodeproj
Create your DeveloperSettings.xcconfig file at/Users/name/projects/SharedXcodeSettings/DeveloperSettings.xcconfig
Then create a plain text file in it: SharedXcodeSettings/DeveloperSettings.xcconfig and
give it the contents:
CODE_SIGN_IDENTITY = Mac Developer
DEVELOPMENT_TEAM = <Your Team ID>
CODE_SIGN_STYLE = Automatic
ORGANIZATION_IDENTIFIER = <Your Domain Name Reversed>
DEVELOPER_ENTITLEMENTS = -dev
PROVISIONING_PROFILE_SPECIFIER =Set DEVELOPMENT_TEAM to your Apple supplied development team. You can use Keychain
Access to find your development team ID.
Set ORGANIZATION_IDENTIFIER to a reversed domain name that you control or have made up.
Note that PROVISIONING_PROFILE_SPECIFIER should not have a value associated with it.
You can now open the NetNewsWire.xcodeproj in Xcode.
Now you should be able to build without code signing errors and without modifying
the NetNewsWire Xcode project. This is a special build of NetNewsWire with some
functionality disabled. This is because we have API keys that can't be stored in the
repository or shared between developers. Certain account types, like iCloud and Feedly, aren't
enabled and the Reader View isn't enabled because of this.
If you have any problems, we will help you out in the forum (see above).