Decoupling to OSS Libraries
Hey this is Isaac,
I met with some dear friends, Danny and Audrey Roy Greenfeld, in Baltimore for a mini-sprint on the air web-dev framework. Walking around a science museum while brainstorming and cafe-hopping while hacking together was a blast.
During the sprint I created a new testing example (unit, integration, and end-to-end playwright tests) and began extracting features from private codebases into small, public libraries. I also learned that a late evening espresso martini is not the best for restful sleep.
I was tired of having similar code in multiple apps and wanted to build with others more. The fix is to extract private logic into small, shared libraries. I'm introducing three of those extractions today.
I hope you'll take a look and contribute. They are in the very early stages, so they are great projects to join.
If you don't know how to start, just reply to this email. I'm doing this to code with more people and would be happy to help you get started :)
The Build: A Tiny Clerk Auth Wrapper
I had GitHub OAuth in one app and Google OAuth in another. It wasn't ideal, but I kept delaying the fix because of other priorities.
Then Hamel Husain created a great example of using Clerk for authentication with air. Then Danny and Audrey started the airclerk library based on that example, and I quickly joined in on the fun.
Nearly every commercial air app needs auth, so an OSS library that everyone can improve will be invaluable to the air ecosystem.
Clerk is nice because it’s managed auth, and you can easily get many types of authentication without writing much code. Clerk’s generous free tier means I can simplify my code and get more auth options for users in the process.
So we worked on airclerk: a tiny library that provides Air routes and dependencies for Clerk auth.
- The Setup: You drop it in with a single app.include_router(airclerk.router).
- The Usage: You protect routes with a require_auth dependency.
- Demo App: The tests/demo.py file shows how to build a real app around it (SessionMiddleware, Clerk JS, protected routes) without bloating the library itself.
For the full code and demo, check out the repo.
The Learn: Use AI for Extraction
AI is perfect for extracting existing, tested code. I used it to peel a user feedback pattern into a new module, airfeedback.
My apps had similar logic for adding a feedback button and modal that stores user feedback, timestamps, user id, and the current route.
AI came close to one shotting an extraction with this prompt:
"Extract the user feedback feature into a new, self-contained module. I will later move it to a separate pypi library, so I can only extract generalizable pieces without assuming a particular database or storage mechanism."
I got a single file module without changing behavior that used a callback function to keep the storage mechanism separate.
This is one thing AI can do almost perfectly in one shot: transformation without invention. It felt safe because these paths were already tested and running in production. I was only asking for a mechanical refactor to save me some time. The result was a new and cleanly decoupled library very, very quickly.
The Refactor: From Copied Tags to One Clean Import
Every app I build needs the same SEO and social metadata: title, description, Open Graph, Twitter cards, favicons, and JSON-LD.
The old way: Every app had its own block of <head> tags. Setting these up is a pain every time because the details are tedious to check and easy to get wrong. I had small suboptimal SEO or social sharing issues scattered on different apps.
The new way: I pulled all this logic into a single library, airheads. Its only job is to render that sweet, sweet metadata consistently and correctly. One function, build_social_head(), orchestrates everything.
I deleted a bunch of duplicated and inconsistent code from three different applications and replaced it all with a single import. Now, one update to airheads fixes or improves metadata across every single project.
Until next week,
Isaac