Decoupling to OSS Libraries
Hey this is Isaac,
I met with Danny and Audrey Roy Greenfeld in Baltimore for a mini-sprint on the air web-dev framework. Science museum 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 does not help restful sleep.
I was tired of having similar code in multiple apps and wanted to build with others more. The fix: extract private logic into small, shared libraries. I'm introducing three extractions today.
Take a look and contribute. They are in the 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 an example of using Clerk for authentication with air. Danny and Audrey started the airclerk library based on that example, and I joined in.
Nearly every commercial air app needs auth, so an OSS library that everyone can improve will help the air ecosystem.
Clerk is managed auth with many authentication types and little code. Clerk's free tier lets me simplify my code and offer more auth options.
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 excels at 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 nearly one-shotted the 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 well in one shot: transformation without invention. It felt safe because these paths were already tested and running in production. I was asking for a mechanical refactor. The result was a cleanly decoupled library, fast.
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 tedious to check and easy to get wrong. I had suboptimal SEO or social sharing issues scattered across 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