Deterministic short IDs
Normalizes the URL, hashes it with SHA-256, and Base62-encodes the first bytes into a compact ID.
01 · Why it exists
A URL shortener should not require another SaaS account.
Most URL shorteners are either closed services with opaque policies or open-source apps that expect a database server and a larger hosting footprint. smawl lives between those options.
It is designed to be forked and deployed as a small Vercel app: two serverless functions, a KV store, a static frontend, and enough guardrails to be useful in real projects.
Core behavior
Small IDs, repeatable results, and abuse limits.
Idempotent shortening
Submitting the same URL returns the same short link instead of creating duplicate records.
Collision handling
If an ID collides with a different URL, the algorithm re-hashes with an incrementing nonce.
Rate limiting
Uses Vercel KV counters with anonymous, whitelisted, and trusted-app tiers.
02 · API
Two endpoints cover the product surface.
| Endpoint | Behavior |
|---|---|
POST /api/shorten |
Accepts a URL and optional custom ID, then returns a short URL. |
GET /:shortId |
Looks up the ID and sends a 302 redirect to the original URL. |
customId |
Optional 3 to 10 character alphanumeric alias. |
| Error response | Returns structured JSON for API errors and an HTML page for unknown short IDs. |
03 · Architecture
Serverless functions in front of one KV store.
| File | Role |
|---|---|
api/shorten.js |
Serverless entry point for shortening requests. |
api/[shortId].js |
Serverless redirect handler. |
src/shorten.js |
Validation, URL normalization, hashing, collision handling, and KV writes. |
src/rateLimit.js |
Multi-tier rate limiting with KV and in-memory fallback. |
public/ |
Static frontend. |
tests/ |
Jest coverage for validation, hashing, idempotency, collisions, and rate limits. |
Deploy your own shortener.
Fork the source, connect Vercel KV, set the environment variables, and deploy.