URL Encoding: The Developer's Swiss Army Knife You're Probably Using Wrong

URL Encoding: The Developer's Swiss Army Knife You're Probably Using Wrong

If you've built anything that touches the web, you've dealt with URL encoding. And if you're honest, you've probably Googled "encodeURI vs encodeURIComponent" at least five times this year. I know I have.

Here's the mental model that finally made it stick for me:

The TL;DR

• encodeURI() = "I'm encoding a complete URL" → keeps structural chars like / ? & #
• encodeURIComponent() = "I'm encoding ONE piece of data" → encodes EVERYTHING except A-Z a-z 0-9 - _ . ! ~ * ' ( )

When Things Go Wrong

Last week I spent an hour debugging a 500 error from a payment gateway. The culprit? I used encodeURI() on a query parameter that contained a # character. The browser interpreted everything after # as a fragment identifier and never sent it to the server. encodeURIComponent() would have caught it.

The 3 Rules I Now Live By

1. Query string values → ALWAYS encodeURIComponent(). No exceptions.
2. Full URLs → encodeURI(), but only if you're sure no component contains special chars.
3. When in doubt → encodeURIComponent(). Worst case: you encode too much. Best case: you avoid a bug.

A Free Tool for When You're Lazy

Sometimes I just want to paste a gnarly URL and see what happens — especially when it's 200 characters long and I don't want to open DevTools. I built a free URL encoder/decoder that runs entirely in the browser. No uploads, no ads, no signup. Just paste and encode.

What URL encoding footgun have you stepped on? I'd love to hear your war stories in the comments.