If you've ever opened a Node.js project on your Mac and watched the fans spin up, the beachball appear, and iCloud Drive consume 100% of a CPU core — you've hit one of the most common frustrations for macOS developers. Here's why it happens, and what you can do about it.
Why iCloud chokes on node_modules
iCloud Drive is designed for documents, photos, and everyday files. It treats every file the same way: detect a change, queue it for upload, sync it individually to Apple's servers. This works fine when you're editing a Pages document or saving a PDF.
The problem starts when you run npm install.
A typical Node.js project's node_modules folder contains thousands of tiny files. A fresh create-react-app project installs around 1,300 packages, which expand to over 20,000 files. A medium-sized Next.js project can easily hit 40,000+ files in node_modules alone.
iCloud Drive doesn't know these files are disposable build artifacts. It sees 20,000 new files appear and tries to sync every single one. Each file gets:
- A metadata check against Apple's servers
- An individual upload queue entry
- A file watcher to track future changes
- An entry in the local iCloud database
Multiply that by 20,000–40,000 files, and your Mac's cloudd process is suddenly doing millions of operations. The result: your fans spin up, mds_stores and cloudd eat CPU, and Finder becomes unresponsive.
What makes it even worse
It's not just the initial install. The problem compounds:
- Every
npm installtriggers a full churn. Adding a single package can change hundreds of files innode_modules. - Build caches add to the pile.
.next,dist,build,.cache— these regenerate constantly during development. .gitobjects are invisible churn. Git stores every commit as hundreds of tiny objects.git commitcreates new files that iCloud immediately tries to sync.- Multiple projects multiply the problem. If you have 5 Node.js projects in iCloud Drive, you're syncing 100,000+ files that change constantly.
Apple hasn't added any exclusion mechanism to iCloud Drive. There's no .icloudignore file. No way to tell iCloud "skip this folder." Every file is treated the same, whether it's a contract PDF or a transpiled Babel helper.
How to fix iCloud node_modules freezing
Fix 1: Move your projects out of iCloud Drive
The simplest fix: don't put code projects in iCloud Drive. Move them to a local-only folder like ~/Developer or ~/Code.
mv ~/Library/Mobile\ Documents/com\~apple\~CloudDocs/Projects/my-app ~/Developer/my-appPros: Instant fix, zero configuration.
Cons: You lose automatic cloud backup. If your Mac dies, your code is gone (unless you push to Git regularly).
Fix 2: Add node_modules to .gitignore (you're probably already doing this)
If your projects are already git-tracked with node_modules in .gitignore, that helps with Git — but iCloud Drive ignores .gitignore. iCloud syncs everything it can see, regardless of Git configuration.
This fix helps your Git workflow but doesn't solve the iCloud problem.
Fix 3: Use an external drive or separate partition
Some developers keep projects on an external SSD or a separate APFS volume not synced to iCloud. This works but adds friction: you need to remember which drive has which project, and you lose the convenience of having everything in your home folder.
Fix 4: Use a sync tool that understands code projects
The root problem is that iCloud Drive treats all files identically. A better approach is a sync tool that:
- Automatically excludes
node_modules,.git,venv, build caches, and other artifacts - Syncs only the source files that actually matter
- Runs on your schedule, not constantly in the background
- Works locally without uploading to any cloud server
That's exactly what LSyncer does. It's a macOS app built specifically for developer workflows — it syncs your project folders while skipping the tens of thousands of files that make iCloud choke. No subscription, no cloud servers, just fast local sync with smart defaults.
Prevention: best practices for code on macOS
Regardless of which fix you choose, these habits help:
- Keep projects in
~/Developeror another non-iCloud folder by default. - Push to Git regularly. Remote repositories are your real backup, not iCloud Drive.
- Monitor
clouddCPU usage. Open Activity Monitor → search forcloudd. If it's consistently above 30% CPU, something in iCloud is churning. - Check which folders iCloud is syncing. Go to System Settings → Apple ID → iCloud → iCloud Drive → Options to see what's included.
Frequently asked questions
Why does iCloud try to sync node_modules at all?
iCloud Drive has no concept of "build artifacts" or "dependencies." It sees a new folder with files and syncs everything. Unlike Git, which uses .gitignore to skip files, iCloud has no exclusion mechanism.
Can I add a .icloudignore file?
No. Apple hasn't implemented any ignore-file support for iCloud Drive. There's no official workaround, no hidden preference, and no API to exclude specific folders from syncing.
Is this an Apple bug or a feature gap?
It's a design limitation. iCloud Drive was built for consumers — documents, photos, and personal files. It wasn't designed for the file patterns that software development creates (thousands of small, frequently changing files in deeply nested directories).
Does this affect other cloud sync tools like Dropbox or Google Drive?
Yes, to varying degrees. Dropbox and Google Drive also try to sync everything, but both support ignore files (.dropboxignore for Dropbox via Smart Sync, and selective sync for Google Drive). iCloud Drive has no equivalent feature.
Will Apple ever fix this?
There's no indication Apple plans to add developer-friendly exclusions to iCloud Drive. The problem has existed since iCloud Drive launched in 2014, and Apple's focus remains on consumer use cases.