Managing Internal Swift Packages Across macOS Projects - Symlinks and Local Dependencies
Managing Internal Swift Packages Across macOS Projects
If you maintain internal Swift packages shared across multiple macOS projects, you have felt the pain. Versioning gets messy, CI breaks because of tag conflicts, and iterating on a shared library while developing the consuming app is painfully slow.
The Registry Approach and Its Problems
The standard advice is to publish packages to a private registry or use git tags for versioning. This works for stable, rarely-changed dependencies. But for internal libraries that evolve alongside your apps, the version-tag-push-resolve cycle adds minutes of friction to every change.
You end up in a loop: edit the package, commit, tag, push, go to the consuming project, update the dependency, resolve, build, find a bug, go back to the package. It kills flow.
Symlinking Actually Works
What actually works is symlinking the package directory into your project. In your Package.swift, use a local path dependency pointing to the symlinked directory. When you edit the package source, the changes are immediately available in the consuming app - no commit, no tag, no resolve step.
The setup is simple. Keep your shared packages in a known directory. In each consuming project, create a symlink to the package directory and reference it as a local dependency during development. For CI and release builds, switch the dependency to the git URL with a version tag.
Making It Work with AI Agents
When AI coding agents work on your codebase, they need to understand where shared code lives. If your internal packages are symlinked, the agent can navigate into them and make cross-package changes in a single session. With versioned registries, the agent would need to work across separate repositories - a much harder coordination problem.
This is one of those cases where the simpler local approach beats the "proper" infrastructure approach for small teams and solo developers building macOS apps.
Fazm is an open source macOS AI agent. Open source on GitHub.