DEV Community: Michael Yousrie

UTM conventions that stop your analytics turning to mush

Michael Yousrie — Fri, 31 Jul 2026 10:42:05 +0000

Most broken analytics I have seen were not broken by a bug. They were broken by three people tagging links slightly differently for six months.

UTM parameters have no schema. Nothing validates them. Your analytics tool takes whatever string you put in utm_source and treats it as gospel, which means the discipline has to live in you, not the tool. Here is a convention that takes ten minutes to adopt and saves you from a report you cannot trust.

The five parameters, and what each is actually for

utm_source: where the click came from. A single named place: newsletter, instagram, partner-acme.
utm_medium: what kind of channel it is: email, social, cpc, qr, referral.
utm_campaign: which initiative it belongs to: spring-launch, black-friday-2026.
utm_content: which specific link, when one page has several: header-cta, footer-link.
utm_term: paid keyword. Mostly vestigial unless you are running search ads.

The distinction people get wrong is source versus medium. Source is the place, medium is the type. Instagram is a source; social is a medium. Your newsletter is a source; email is a medium. If you find yourself putting instagram in medium, the whole report will fragment later.

Rule 1: lowercase everything, always

This is the single highest-value rule, so it goes first.

utm_source=Instagram
utm_source=instagram
utm_source=INSTAGRAM

Most analytics tools treat those as three different sources. You will not notice for a month. Then you will open a report, see Instagram split across three rows, and have no clean way to merge history.

Lowercase everything. No exceptions, no judgment calls.

Rule 2: hyphens, never spaces or underscores

A space becomes %20 and looks broken in reports. Underscores are fine technically but mixing them with hyphens gives you the same fragmentation problem as casing.

❌ utm_campaign=Spring Launch
❌ utm_campaign=spring_launch
✅ utm_campaign=spring-launch

Pick hyphens. Write it down. Done.

Rule 3: date your campaigns

utm_campaign=black-friday seems fine until it is your third Black Friday and every year is stacked into one row.

✅ utm_campaign=black-friday-2026
✅ utm_campaign=2026-03-product-launch

Year-first works well if you want campaigns to sort chronologically.

Rule 4: never tag internal links

This is the one that silently corrupts data.

If you tag a link from your own homepage to your own pricing page, most analytics tools start a new session at that click and overwrite the original referrer. The visitor came from a newsletter, clicked one internal link, and is now attributed to your own site.

UTMs are for traffic arriving from outside. Internal navigation is what your normal page-path reporting is for.

Rule 5: keep a canonical list

Not a spreadsheet nobody opens. A short list in whatever doc your team actually reads:

sources:  newsletter, instagram, tiktok, linkedin, youtube, partner-<name>
mediums:  email, social, cpc, qr, referral, print
campaign: <yyyy>-<mm>-<short-name>
content:  header-cta, inline-link, footer-link, bio-link

The rule is: if it is not on the list, it does not get used until it is added to the list. That single sentence is what prevents drift, because the failure mode is never one bad decision, it is fifty small ones.

Rule 6: think about what the user sees

A URL like this in an Instagram bio is ugly, and it leaks your internal campaign naming to anyone who looks:

https://example.com/pricing?utm_source=instagram&utm_medium=social&utm_campaign=2026-03-launch&utm_content=bio-link

This is where a short link earns its place. The tagged URL becomes the destination, and the thing you publish stays clean. You keep the attribution and the reader gets a link that fits.

It also means the tagging lives in one editable place. Get a UTM wrong on a printed QR code and you are reprinting; get it wrong behind a short link and you fix the destination.

Rule 7: QR codes need `utm_medium=qr`

Scans from print are not "direct" traffic, but that is where they land if you do not tag them. Tag the URL behind the code, and if the same campaign runs on a poster and a flyer, separate them with utm_content:

utm_source=poster&utm_medium=qr&utm_campaign=2026-03-launch&utm_content=cafe-window

Now "did the flyers do anything" is a question with an answer.

A worked example

Spring launch, promoted through the newsletter, Instagram bio, and a printed flyer:

# newsletter, main button
?utm_source=newsletter&utm_medium=email&utm_campaign=2026-03-spring-launch&utm_content=header-cta

# instagram bio link
?utm_source=instagram&utm_medium=social&utm_campaign=2026-03-spring-launch&utm_content=bio-link

# flyer QR code
?utm_source=flyer&utm_medium=qr&utm_campaign=2026-03-spring-launch&utm_content=cafe-window

Same campaign across all three, so they roll up. Different sources and mediums, so they break down. That is the whole point.

The check that catches drift

Once a month, list your distinct utm_source values. If you see instagram and Instagram, or ig and insta, drift has started. Fix the convention now, because merging historical rows is unpleasant and sometimes impossible.

I build Swyfty, a short-link and analytics tool, which is why I have opinions about this. But none of the above needs my product or any product. It needs a list of allowed values and the discipline to stick to it.

The tooling is never what makes attribution work. Consistency is. A boring convention applied every time beats a sophisticated analytics stack fed inconsistent strings, every single time.

Bitly alternatives: the limit that bites is data retention, not links

Michael Yousrie — Fri, 31 Jul 2026 10:42:03 +0000

If you are comparing link shorteners, you have probably lined them up by price per month and by how many links each tier allows. That is the comparison every pricing page invites you to make, and it hides the limit that actually bites.

For click analytics, the limit that matters is how long your data survives.

What Bitly actually meters

Bitly's published pricing, as of July 2026:

Plan	Price	Links/month	Click data history
Free	$0	5	(not offered)
Core	$10/mo, annual only ($120/yr)	100	30 days
Growth	$29/mo annual, or $35/mo	500	4 months
Premium	$199/mo annual, or $300/mo	3,000	1 year
Enterprise	custom	custom	2 years

Clicks themselves are unlimited on every tier. That sounds generous, and it is the number everyone quotes. But look at the right-hand column.

On Core, your click history is 30 days. Run a campaign in March, come back in May to see how it did, and there is nothing to see. The clicks happened. The record of them expired.

The second thing worth noticing: city-level and device tracking sit on Premium. That is $199/month billed annually, or $300 month to month. If "I just want to know where my clicks come from and what they are opening it on" is your entire requirement, Bitly's answer is its top self-serve tier.

None of this makes Bitly a bad product. It is a mature platform with a real enterprise business, and the pricing is shaped for that buyer. But if you are one person with some links and a question about them, you are shopping in the wrong aisle.

The question to ask every shortener

Before you compare prices, ask this:

"In six months, can I still see what happened to a link I made today?"

It reframes the whole evaluation. A $10/month plan that forgets everything after 30 days is not cheaper than a $7/month plan that does not. It is a different product that happens to have a similar-looking price.

Then two follow-ups:

"Is the granularity I need on the tier I can afford?" Country-level is common on cheap plans. City and device often are not. Decide which you actually need before you pay for a tier that gives you neither.

"What happens to my links if I stop paying?" This is the one people find out about late. A short link is a promise printed on things you no longer control: business cards, packaging, an old tweet, someone else's blog post. If those links go dead or start showing a parked page when you downgrade, you have handed your reputation to a billing relationship. Ask before you print.

A checklist for comparing link tools

Data retention window. The single most under-compared spec. Get the number in months.
Granularity per tier. Country, city, device, browser, referrer, unique versus repeat. Which of those are on the plan you would actually buy?
Unique versus total clicks. If a tool only reports total clicks, one enthusiastic person and a preview bot can look like a successful campaign. You want both numbers.
What happens on downgrade or cancellation. Do existing links keep resolving?
Link creation limits. Monthly caps are common. If you generate links programmatically, a 100/month cap disappears fast.
Custom domain cost. Often the real jump between tiers.
Is there an API on the plan you can afford? If links need to come out of your own tooling rather than a dashboard, check this early. It is frequently gated.
Export. Can you get a CSV out? If the answer is no, the data was never really yours.

That list is the useful part of this post. Run it against any tool, including mine.

Where Swyfty fits, and where it does not

Full disclosure: I build Swyfty, so treat this section as the biased part and check it yourself.

It exists because of the gap above. Short links, click analytics, QR codes and a link-in-bio page behind one login, with a REST API. Analytics include country and city, device, browser, referrer, and unique versus repeat visitors, and they are on the $7/month plan rather than a $199 one. There is CSV export, so the data leaves with you. Free covers 3 links, 500 visits each, and one bio page, with a short interstitial before each redirect; Pro is $7/month or $60/year and removes the interstitial, adds custom slugs, QR codes and hourly checks that your destination URLs are still alive.

Now the honest part, because a comparison post that only lists strengths is an ad. Swyfty does not have:

Team accounts or multiple seats
White-label custom domains
Retargeting pixels
A/B testing of links
Scheduled link expiry

If you need branded custom domains at scale, or several people working in the same account with permissions, Bitly or Rebrandly is genuinely the better buy and I would rather you went there than churned out of mine in a month. If all you want is a bio page and nothing else, Linktree has a much larger template ecosystem.

It is also early. There is no traction to point at, no testimonials, and I am not going to invent any. What I can tell you is what the product does and what it costs.

The decision rule

Are you buying link infrastructure for a team, or answers about your own links?

If it is a team, buy the platform. Seats, permissions, branded domains and long retention are what those prices are for, and they are worth it at that size.

If it is answers, then retention and granularity are the only specs that matter, and you should not have to reach an enterprise tier to keep six months of your own click history.

Either way: compare the retention column first. It is the one nobody puts in the comparison table, and it is the one you notice in six months when you go looking for a number that is no longer there.

Looking for a Beamer alternative? Check the pricing model before the feature list

Michael Yousrie — Thu, 30 Jul 2026 18:24:01 +0000

If you are shopping for a changelog tool, you have probably noticed that the feature lists all converge. Everyone has a widget, a hosted page, some analytics, and a screenshot of a tidy "what's new" panel. Feature tables are where these tools look identical.

Pricing models are where they stop looking identical, and that is the part that decides what you pay in a year.

Here is what to actually check, using Beamer as the reference point since it is the tool most people compare against first.

What Beamer costs

Beamer's published pricing, as of July 2026:

Plan	Monthly	Annual	MAU cap
Free	$0	$0	1,000 (1 teammate)
Starter	$59	$49/mo	5,000
Pro	$119	$99/mo	10,000
Scale	$299	$249/mo	50,000

Extra users run $50/month per additional 5,000 MAU. The Feedback module (roadmap, idea voting) and the NPS module are separate add-ons at $99/month each.

None of that is a criticism. Beamer is a capable product engagement platform, and if you want announcements, segmentation, surveys, and a feedback board in one dashboard, the price is reasonable for what it does. The problem is that a lot of people buying it only ever wanted the changelog.

The pricing axis matters more than the feature list

Notice what Beamer bills on: monthly active users.

Think about what that means over time. Your changelog workload is basically constant. You ship something, you write a paragraph about it, you publish. That work is the same whether 500 people use your app or 50,000.

Your bill is not constant. It scales with your app's success. Cross 10,000 MAU and you are on a $119/month tier for the same paragraph you were writing at $0. Cross 50,000 and it is $299. You did not use more of the tool. You just grew, and the tool is priced to capture that growth.

This is the single biggest thing to check when comparing changelog tools, and it is the thing feature tables never show you. Ask one question of every tool on your list:

If my traffic goes up 10x and my publishing habits do not change at all, what happens to this bill?

If the answer is "it goes up a lot," you are not buying a changelog. You are buying a percentage of your own growth.

A checklist for comparing changelog tools

Beyond the pricing axis, these are worth checking before you commit, roughly in order of how often they bite people later:

Is the widget CSS-isolated? If it renders into your page's normal DOM, it inherits your global styles and your resets fight its layout. Shadow DOM isolation is the fix. Ask, or open devtools on their demo and look for a #shadow-root.
Does the widget fail silently? A marketing widget must never break the host app. If their CDN has a bad day, your product should not.
What happens when you stop paying? Does the hosted page stay up, redirect, or 404? Your changelog URLs may be linked from release emails and docs.
Can you get your content out? Look for an export or an RSS feed. Release notes are writing you own.
Does the free tier carry a badge? Many do, including mine. That is a fair trade for free, but you should know before you embed it, not after.
How much of the product is add-ons? A cheap base tier plus two mandatory $99 modules is not a cheap tool.
Do you actually need segmentation? It is the feature most often used to justify the jump to a higher tier, and the one solo products least often need. If everyone sees the same feed, do not pay for targeting.

That list is the whole point of this post. Run it against any tool, including the one I build.

Where Patchlog fits, and where it does not

Full disclosure: I build Patchlog, so treat this section as the biased part and check it yourself.

It exists because of the pricing axis above. It is a drop-in changelog widget plus a hosted page, priced flat at $7/month (or $5/month billed yearly) rather than per monthly active user. Traffic growth does not change the bill. The free tier gives you one project and 25 updates, and it shows a small "Powered by Patchlog" badge, which is how the free tier pays for itself.

The install is one tag, no SDK and no npm install:

<script src="https://cdn.patchlog.io/widget.js"
        data-project="your-project-id"
        data-position="bottom-right"
        async></script>

It renders in a Shadow DOM, so it does not collide with your CSS, and it works the same in React, Vue, Rails, or plain HTML.

Now the honest part, because a comparison post that only lists strengths is an ad. Patchlog does not have:

User segmentation or targeting. Everyone sees the same feed.
NPS surveys, roadmaps, or feedback boards.
Email notifications or digests.
A public API.

Those are real gaps, not roadmap teases. If you need to announce a feature to enterprise accounts only, run NPS surveys, or collect and vote on feature requests, Patchlog is the wrong tool and Beamer or Canny is genuinely the better buy. Pay them.

The decision rule

It comes down to one question: are you buying a changelog, or a product engagement platform?

If you need segmentation, surveys, feedback boards, and a team dashboard, buy the platform. Those tools are priced the way they are because they do a lot, and the MAU model is the standard way that category charges.

If what you actually want is for your users to notice you shipped something, you want a widget, a hosted page, and a flat bill. Anything that meters your changelog against your own growth is charging you for the wrong variable.

Either way, check the pricing axis before the feature table. The feature table is where these tools look the same. The pricing axis is where they differ, and it is the one you live with.

Do people actually read your changelog? Here is how to measure it

Michael Yousrie — Thu, 30 Jul 2026 18:13:11 +0000

You ship updates. Maybe a changelog widget, maybe a "what's new" page, maybe just a post that says "we shipped X." And then you have no idea if a single person read it.

That is the uncomfortable part of shipping in public. You put the work in, you announce it, and the announcement disappears into the void. Views are vanity. What you actually want to know is whether anyone cared enough to click through and look.

You can measure that. Here is the setup I use.

The problem with raw view counts

Most changelog tools and update feeds will happily tell you how many times a page was loaded. That number lies to you in two directions:

Bots, prefetchers, and your own reloads inflate it.
A "view" tells you a page rendered, not that a human read a word of it.

The signal you actually want is intent. Someone read an update, and it mattered enough that they took the next step and clicked the link in it. That click is worth a hundred passive views, because a human chose to make it happen.

So the trick is simple. Make every link you put in an update a measured link.

Wrap your update links in tracked short links

Whenever an update contains a link (to the new feature, to a doc, to a demo), do not paste the raw URL. Run it through a short-link tool that records analytics on the redirect. Now every time someone follows that link, you capture:

Referrer, so you know whether the click came from the in-app widget, the hosted page, an email, or somewhere you did not expect.
Device and browser, so you know if the feature you built for developers is actually being opened on phones.
Country, which feeds timing and localization decisions.
Unique vs repeat, so you can tell ten curious people apart from one person clicking ten times.

None of that requires a heavy analytics stack or a cookie banner. It is just a redirect that counts.

Reading the data (this is the part that changes what you do)

A tracked link turns a vague feeling into a decision. A few patterns that show up in real data:

Clicks cluster on the hosted page, not the in-app widget. Your in-app placement is too quiet. Move it.
High clicks, but all repeat visitors. Your existing users care, but the update is not reaching anyone new. That is a distribution problem, not a product one.
A feature you were proud of gets almost no clicks. Before you assume nobody wants it, check whether the announcement itself was clear. Often the feature is fine and the release note was the noise.
One channel massively outperforms the rest. Now you know where to spend your next announcement.

The point is not the dashboard. The point is that "did anyone read it" stops being a shrug and becomes something you can answer and act on.

How I wire this up

Full disclosure, both tools here are mine, which is exactly why I built this loop for myself.

I keep my product's release notes in a changelog widget. I build Patchlog, a drop-in changelog widget, so that part is easy for me. Every link that goes into an update, I route through a short link with analytics. I also build Swyfty, so I use that. The result is that when I ship something, I am not guessing whether it landed. I can watch the clicks come in, see where they came from, and see whether it was the same five people or someone genuinely new.

You do not need my tools to do this. Any changelog surface plus any short-link tool that exposes referrer and device data will get you there. The habit is the valuable part. Never ship an update with a naked link in it, and read the clicks a week later like a scoreboard.

Shipping is only half the job. Knowing whether the shipping was heard is the other half, and it turns out to be cheap to measure once you set it up.

How to write release notes people actually read

Michael Yousrie — Wed, 15 Jul 2026 04:05:15 +0000

Most release notes are written for the person who wrote them. That is why nobody reads them.

You finish a sprint, you scroll your merged PRs, and you turn them into bullet points. The result is technically accurate and completely useless to the person reading it, because it answers "what did we do" when the reader is asking "does any of this affect me?"

I build Patchlog, a changelog widget, which means I end up reading a lot of other people's release notes. The good ones are rare and they all do roughly the same things. Here is what separates them.

Lead with what the user can now do

The most common failure is describing the change instead of the outcome.

Refactored the export pipeline to use a queued job.

Nobody outside your team can act on that. What actually changed for them?

Exports no longer time out on large accounts. Big exports now run in the background and email you when they're done.

Same commit. The second version tells a user who gave up on exports three months ago that it is worth trying again. That is the entire job of a release note.

A quick test: read your entry and ask "so what?" If the answer is not in the text, rewrite it.

"Fixed a bug" is not a release note

Vague fix entries are worse than no entry, because they take up space and train people to skim past your changelog.

Fixed a bug in bulk edit.

Compare:

Bulk edit no longer drops your selection when you paginate.

The specific version does something the vague one cannot: it reaches the exact person who hit that bug, and tells them it is safe to come back. That person is often one bad experience away from churning. Name the broken thing.

Group by impact, not by ticket

Your issue tracker is not an outline. Users do not care that PROJ-412 and PROJ-419 were separate tickets, or that one was a bug and one was a chore. They care that search got faster.

Group related work into one entry that describes the user-visible result, even if it spanned six PRs. Split one PR into two entries if it changed two unrelated things. The unit of a changelog is the change a person notices, not the unit of work you tracked.

Cut ruthlessly, then lead with the one that matters

Nobody reads fourteen bullet points. The instinct is to list everything, because you did all of it and it all felt significant while you were doing it. But readers scan for the single line that affects them, and every dependency bump you include makes that line harder to find.

Two rules that help:

If a change is invisible to users, it does not need an entry. Your internal refactor is real work, but a changelog is not a performance review.
Put the one thing most people will care about first. Not chronological, not grouped by type. Most important, first.

Signal beats completeness. A three-line changelog people read beats a twenty-line one they scroll past.

Use their words, not your internal names

Every team accumulates internal vocabulary. The feature is called "Workspaces" in the UI but everyone on the team still calls it "orgs" because that was the table name. Then it hits the changelog as "orgs" and readers have no idea what shipped.

Write the noun the user sees in the interface. If you renamed something, say both names once so people can bridge it.

Say why when it is not obvious

Some changes look like downgrades until you explain them. Lower limits, a removed option, a changed default.

Changed the default session length to 7 days.

Reads as arbitrary, maybe hostile. Add one clause:

Sessions now last 7 days instead of 30, so a forgotten open tab on a shared computer stops being a security problem. You can raise it in Settings.

You do not owe an essay. One clause of reasoning turns a complaint into a shrug.

Pick a cadence and let the small stuff batch

Two failure modes. Publish every merge and your changelog becomes a commit log nobody follows. Publish twice a year and each post is an unreadable wall of everything.

What works for most small products: batch the small fixes into a regular post on a predictable rhythm, and give a genuinely big feature its own entry when it lands. Predictability matters more than frequency. A changelog that updates every other Friday reads as a product with a pulse. One that goes quiet for five months reads as abandoned, even when you are shipping the whole time.

If writing them up is what keeps slipping, write several ahead and schedule them out. Drafting is the part that fails, not publishing.

A before and after

Before:

Fixed a bug

Updated dependencies

Refactored the importer for performance

Added new field to API response

Misc improvements

After:

CSV imports are about 4x faster. A 50,000 row file that used to take two minutes now finishes in under thirty seconds.

Imports no longer fail silently on a bad row. You get a list of the rows that failed and why, instead of a generic error.

The /orders API response now includes fulfilled_at. Existing fields are unchanged.

Shorter in spirit, longer on the page, and every line answers "so what?"

Where they go matters as much as how they read

Worth saying plainly: the best-written release notes still fail if they live somewhere nobody visits. A Notion doc, a #releases Slack channel, a /changelog route linked from the footer. All are places users go zero times a month.

That gap is the reason Patchlog exists, so treat this paragraph as the biased one. But the underlying point holds regardless of what you use, including a plain page you build yourself: put the notes where people already are, in the product, rather than hoping they come looking.

The short version

Lead with the outcome, not the change.
Be specific about fixes. Name what was broken.
Group by what the user notices, not by ticket.
Cut anything invisible, and put the important line first.
Use the words in your UI.
One clause of "why" for anything that looks like a downgrade.
Predictable cadence beats frequent or exhaustive.

None of this takes longer than what you are doing now. It mostly takes writing the entry after you have stopped thinking like the person who wrote the code.

I built a PHP microframework where the method name is the route

Michael Yousrie — Sun, 12 Jul 2026 19:26:25 +0000

I kept starting the same kind of small PHP project: a quick JSON API, a webhook receiver, a few endpoints behind a static site. Every time, Laravel or Symfony felt like a lot of scaffolding for something that only needed a handful of handlers. So I built a microframework for exactly that middle ground, and I have been building it in public with Claude Code on YouTube.

It is called Batframe, and the whole idea fits in one sentence: your method name is the route.

Extend one class, get endpoints

You extend a base class and write public methods. Each verb-prefixed method becomes an HTTP endpoint whose route is inferred from its name. There is no route file to author and nothing to register.

use Batframe\Batframe;
use Batframe\Http\Request;
use Batframe\Http\Response;

class App extends Batframe
{
    public function index()                     // GET /
    {
        return view('home', ['name' => 'World']);
    }

    public function getUsers()                  // GET /users
    {
        return ['users' => ['ada', 'linus']];   // arrays become JSON automatically
    }

    public function getUser(int $id)            // GET /user/{id}
    {
        return ['id' => $id];
    }

    public function postUsers(Request $request) // POST /users
    {
        return Response::json(['created' => $request->input('name')], 201);
    }
}

(new App())->run();

That is a working app. No config, no route table, no annotations.

The routing convention

The route comes entirely from the method name and its typed parameters.

Method	Route
`index()`	`GET /`
`getUsers()`	`GET /users`
`getUser(int $id)`	`GET /user/{id}`
`postUsers()`	`POST /users`
`putUser(int $id)`	`PUT /user/{id}`
`deleteUser(int $id)`	`DELETE /user/{id}`

The rules are small enough to keep in your head:

The method must start with an HTTP verb (get, post, put, patch, delete, head, options). That sets the HTTP method.
The remaining PascalCase words become lowercased, slash-separated path segments. There is no auto-pluralization, so the path is literal: getUser() is /user, getUsers() is /users.
Typed scalar params (int, string, float, bool) become {placeholder} segments in order. int and float also constrain the match, so /user/abc will not hit getUser(int $id).
A Request-typed param is injected and can sit in any position.
A public method that does not start with a verb is treated as an internal helper and is not routed.

When the app class starts to fill up, related endpoints can move into traits. A verb-prefixed method composed in from a trait registers exactly like an inline one, so you can group routes by feature and keep the app class tiny.

Ergonomics without a framework tax

Return values are turned into responses for you: an array or scalar becomes JSON, a string becomes HTML, null becomes a 204, and a Response is sent as-is. When you want control, the Response helpers are fluent:

Response::json($data)->status(201)->header('X-Trace', 'abc');

Requests read the way you would expect, with input() looking through the JSON body, then the form body, then the query string:

$request->input('name', $default);
$request->bearerToken();
$request->wantsJson();

There is also a small file-based session helper and a file-based cache with per-item TTL, both of which start lazily and need no setup. Views run on BladeOne, so you get familiar Blade syntax without pulling in the rest of a framework. Drop a Blade or HTML file in the pages/ directory and it is served automatically, which makes small static sites trivial.

What it is not

Being honest about scope matters more than a feature list. Batframe intentionally leaves out a middleware pipeline, a DI container, CLI scaffolding, a PSR-7 bridge, and an attribute-based route layer. Those are on the shelf, not shipped, and the routing resolver is kept as a clean seam so an attribute layer could be added later without touching dispatch. If your project needs those things today, reach for Laravel or Symfony. Batframe is for the project that does not.

Built in public with Claude Code

The reason I am sharing it now: I am building Batframe out in the open, one feature per episode, pairing with Claude Code on camera. The sessions and caching helpers, for example, got their own episode. If you want to see how the framework is designed and tested rather than just read the finished code, the series is here:

https://www.youtube.com/playlist?list=PLSohpKg3v4pE

Try it

The fastest way in is the skeleton, which scaffolds a ready-to-run app:

composer create-project michaelyousrie/batframe-skeleton my-app
cd my-app
composer serve

Or add it to an existing project:

composer require michaelyousrie/batframe

PHP 8.1+, MIT licensed. Code and docs are on GitHub: https://github.com/michaelyousrie/batframe

If you build something small with it, or you have opinions about the routing convention, I would genuinely like to hear them.

How to embed a widget on any site without CSS collisions (Shadow DOM)

Michael Yousrie — Sat, 11 Jul 2026 17:56:38 +0000

If you have ever dropped a third-party widget onto a page and watched it either inherit the host site's CSS or quietly break the host's own layout, you have run into the oldest problem in embeddable widgets: the DOM is shared, so styles leak in both directions.

The host page has a global a { color: red } and suddenly every link in your widget is red. Your widget ships a .button class and now the host's own buttons look wrong. Iframes solve isolation but bring their own pain: fixed sizing, awkward communication, and they feel heavy for something as small as a "what's new" panel.

There is a better tool built into every modern browser: the Shadow DOM.

What the Shadow DOM actually does

A shadow root is a separate DOM tree attached to a host element. Styles defined inside it do not leak out, and styles from the outer page do not leak in. It is the same mechanism the browser uses internally for elements like <video> and <input type="range">, where you can see the control but not style its internals.

Here is the whole idea in a few lines:

// 1. Put a host element on the page
const host = document.createElement('div');
host.id = 'changelog-widget';
document.body.appendChild(host);

// 2. Attach a shadow root to it
const shadow = host.attachShadow({ mode: 'open' });

// 3. Everything you render inside is isolated
shadow.innerHTML = `
  <style>
    .panel {
      font: 14px/1.5 system-ui, sans-serif;
      color: #111;
      background: #fff;
      padding: 16px;
      border-radius: 8px;
    }
    a { color: #2563eb; }
  </style>
  <div class="panel">
    <strong>What's new</strong>
    <p>We just shipped dark mode.</p>
    <a href="#">See all updates</a>
  </div>
`;

That a { color: #2563eb } rule only applies inside the shadow root. The host page's global link color cannot reach it, and your .panel class will never collide with a .panel on the host site. No prefixing, no BEM gymnastics, no !important wars.

The boundary is not a wall for everything

A few things cross the shadow boundary on purpose, and knowing which ones saves you hours:

CSS custom properties inherit through. If the host page sets --brand-color, you can read var(--brand-color) inside the shadow root. This is the clean way to let a host theme your widget without exposing your internals.
Fonts loaded on the page are usable inside. @font-face and font files loaded by the host are available, so your widget can match the site if you want it to.
Events retarget. A click inside the shadow tree still bubbles to the host, but event.target is rewritten to the host element so you do not leak your internal structure.
:host styles the host element itself, which is handy for positioning the whole widget from inside.

:host {
  position: fixed;
  bottom: 24px;
  right: 24px;
  z-index: 2147483000;
}

Open vs closed

attachShadow({ mode: 'open' }) lets outside JavaScript reach the tree via host.shadowRoot. mode: 'closed' returns null there. Closed feels safer but mostly just makes debugging harder for you without stopping a determined host page, so open is the pragmatic default for a widget.

Why this matters for embeddable products

The reason this technique is worth reaching for is distribution. If your widget is fully isolated, your install instructions collapse to a single line:

<script src="https://cdn.example.com/widget.js" async></script>

The script creates its host element, attaches a shadow root, and renders. It works the same on a React app, a Rails site, a WordPress theme, or a hand-written HTML page, because it never touches the host's styles and the host never touches its own.

This is exactly how I built the changelog widget for Patchlog. It is a drop-in "what's new" widget for SaaS products: one script tag, rendered inside a Shadow DOM so it never collides with the host site's CSS, with light, dark, and auto theming that reads the host's CSS variables when you want it to. There is a free tier if you want to see the technique in a shipped product rather than a blog snippet.

Takeaways

Reach for the Shadow DOM when you need real style isolation without the weight of an iframe.
Remember the intentional exceptions: CSS variables, fonts, events, and :host.
Use mode: 'open' unless you have a specific reason not to.

Style isolation used to be the hardest part of shipping an embeddable widget. The platform quietly solved it years ago, and most of us just have not switched over yet.

How to add a changelog to any web app with one script tag

Michael Yousrie — Sat, 11 Jul 2026 00:05:39 +0000

You ship all the time. A fix here, a new setting there, a feature you spent a whole weekend on. And your users mostly don't notice.

That gap is expensive. When people can't see a product moving, it feels abandoned, even when you're shipping every week. They churn a little faster, they email asking for things you built a month ago, and all the momentum you're actually creating stays invisible.

The fix is boring and old: a changelog. But not a changelog rotting in a Notion doc nobody opens. One that shows up inside your app, where users already are.

Here's the approach I settled on.

The idea: a widget, not just a page

A "what's new" widget is a small button or badge in your UI. Click it, and a panel slides out with your latest updates. Users see it in the flow of using your product, not on some /changelog page they'd never visit.

You really want three things:

An in-app widget users actually see.
A public page and RSS feed you can link from emails and docs.
A way to write updates in plain language and publish in a click.

The one-tag version

I ended up building a tool for this (honest disclosure below), but the integration is the part worth showing, because it's the pattern any changelog widget should follow:

<!-- Paste before </body> -->
<script src="https://cdn.patchlog.io/widget.js"
        data-project="your-project-id"
        data-position="bottom-right"
        async></script>

One script tag. No SDK, no npm install, no framework coupling. It behaves the same in React, Vue, Rails, or a plain HTML page.

Two implementation details matter, whether you build one of these yourself or evaluate an existing one:

Render it in a Shadow DOM. A changelog widget should not inherit or leak styles. If it uses the host page's global CSS, it will look broken on half the sites it lands on. Shadow DOM isolates it completely.
Fail silently. A marketing widget must never break the host app. If the network call fails, it should quietly do nothing.

What to actually write in it

The tool is the easy part. The discipline is writing updates people care about. A few things that have worked for me:

Tag each entry as New, Fixed, or Improved. People scan, so give them anchors.
Write like a person. "CSV exports were timing out on big accounts, now fixed" beats "Resolved asynchronous export latency regression."
Ship small and often. Ten small updates read as momentum. One giant quarterly post reads as a company that went quiet for three months.
Schedule them. Write the note when you ship the code, set it to publish later, and your changelog stays alive even in a busy week.

Honest disclosure

I build Patchlog, so the snippet above is my own tool. I'm not going to pretend otherwise. It's early: the free tier is one project and 25 updates, which is genuinely what I run on my own projects. I'm sharing the approach because it's helped me, and if it saves you the afternoon it cost me to think through, great.

The actual point

Whatever you use, whether you build it, use mine, or use a competitor, close the gap between shipping and your users noticing you shipped. That gap is quietly costing you retention, and it's one of the cheapest things in your entire product to fix.

What do you use for changelogs today? Always curious how other people handle this.

DEV Community: Michael Yousrie

UTM conventions that stop your analytics turning to mush

The five parameters, and what each is actually for

Rule 1: lowercase everything, always

Rule 2: hyphens, never spaces or underscores

Rule 3: date your campaigns

Rule 4: never tag internal links

Rule 5: keep a canonical list

Rule 6: think about what the user sees

Rule 7: QR codes need utm_medium=qr

A worked example

The check that catches drift

Bitly alternatives: the limit that bites is data retention, not links

What Bitly actually meters

The question to ask every shortener

A checklist for comparing link tools

Where Swyfty fits, and where it does not

The decision rule

Looking for a Beamer alternative? Check the pricing model before the feature list

What Beamer costs

The pricing axis matters more than the feature list

A checklist for comparing changelog tools

Where Patchlog fits, and where it does not

The decision rule

Do people actually read your changelog? Here is how to measure it

The problem with raw view counts

Wrap your update links in tracked short links

Reading the data (this is the part that changes what you do)

How I wire this up

How to write release notes people actually read

Lead with what the user can now do

"Fixed a bug" is not a release note

Group by impact, not by ticket

Cut ruthlessly, then lead with the one that matters

Use their words, not your internal names

Say why when it is not obvious

Pick a cadence and let the small stuff batch

A before and after

Where they go matters as much as how they read

The short version

I built a PHP microframework where the method name is the route

Extend one class, get endpoints

The routing convention

Ergonomics without a framework tax

What it is not

Built in public with Claude Code

Try it

How to embed a widget on any site without CSS collisions (Shadow DOM)

What the Shadow DOM actually does

The boundary is not a wall for everything

Open vs closed

Why this matters for embeddable products

Takeaways

How to add a changelog to any web app with one script tag

The idea: a widget, not just a page

The one-tag version

What to actually write in it

Honest disclosure

The actual point

Rule 7: QR codes need `utm_medium=qr`