Building ComicToEPUB: Why Watch Folders Changed Everything
Honestly, the first version of ComicToEPUB was a weekend project built on a simple premise; pick a folder, hit convert, and wait for the progress bar. It solved the immediate format crisis for files sitting on a drive. Problem solved (or so I thought).
Then I ran into a thread on Reddit where a user was lamenting the "curation tax." They weren't talking about a one-time migration; they were talking about the friction of maintaining a growing library. Every time they added a new volume to their NAS, they had to sit down at their Mac, manually trigger a conversion, and then move the results to their cloud sync folder.
That realization hit me hard. A collection isn't a static archive; it is a living entity. Batch processing is something you do. Automation is something that happens.
The engineering of "Invisible" Automation
I started designing Watch Folders with a single goal; the user should never have to open the app's main window twice. But making an app "disappear" while it works is technically much harder than building a button you click.
Harnessing FSEvents
Implementing this on macOS meant deep-diving into FSEvents. This API is incredibly powerful but notoriously "coarse." If you move a folder containing fifty volumes into a watched directory, FSEvents doesn't just give you a nice, clean list; it fires a flurry of notifications that can overwhelm a background process.
The Debouncing Logic
I had to build in a specific debouncing mechanism. When the system detects a change, the app now waits for a "quiet period" (a few seconds of silence) to ensure the file isn't still being written to the disk or copied over the network from a NAS. Only after that quiet period does the app scan the folder. This prevents the app from trying to decompress a CBZ that is only 40% transferred, which would otherwise trigger a cascade of corruption errors.
Persistence and the Job Store
A background monitor that loses its place after a restart is a liability. I needed to ensure that if you close the app or reboot your Mac, the "watch" resumes exactly where it left off without re-processing the entire drive.
I built a persistent job store using a local database to record the signature of every successful conversion. On startup, the app loads all configured watch folders and compares the directory state against this history. This prevents the "re-discovery" loop where the app tries to convert 500 existing files every time the service initializes.
Rules vs. Intent
The biggest design hurdle wasn't the code; it was the configuration. Different comics need different treatments. A Manga volume needs a Right-to-Left (RTL) flag in the EPUB metadata, while a Western graphic novel needs Left-to-Right.
I briefly considered using machine learning or complex filename parsing to "guess" the orientation, but that felt brittle. Instead, I opted for Intent-based Folders.
Most collectors already organize their storage into Manga and Comics directories. By allowing users to attach specific "Intent Profiles" to different watch folders, the app stays lightweight. One folder monitors for RTL, another for LTR. You drop the file in the right place (which you were going to do anyway) and the automation takes care of the rest.
Performance and Reliability
Watch Folders runs continuously, even when the main app window is closed. This is where the battery and CPU footprint matters. I set the monitor to idle whenever the filesystem is quiet, and I wrapped every operation that touches the NAS in heavy error-handling. If a network drive goes to sleep mid-conversion, the app doesn't crash; it just marks the job for a retry once the volume re-mounts.
The workflow transformation
Once the Watch Folder logic and the FSEvents monitoring were stable, the app moved from being a "utility" to a "service."
Before, the process was: acquire, organize, convert, sync, read. Now, it is: acquire, organize... read.
The "convert" and "sync" steps disappeared into the background. I set up a watch on my external "Acquisitions" folder and pointed the output directly to my Google Play Books upload directory. Now, a volume added to my NAS is waiting for me on my iPad or Kindle within seconds, perfectly formatted and ready for the cloud.
The real lesson
Watch Folders taught me that the best features are the ones that make themselves obsolete. You don't notice the automation until you use a device without it and realize how much manual "management" you've been tolerating.
ComicToEPUB started as a converter. Watch Folders made it a bridge. It’s no longer about changing a file extension; it’s about making sure your library is as fluid as your reading habits.
