Creating a URL Shortener with Cloudflare Workers

Why Build Your Own URL Shortener

Third-party URL shorteners have been around for years, offering convenient link management for social media, marketing campaigns, and sharing long URLs. However, relying on external services introduces risks: services can shut down without warning, change their terms, impose rate limits, or even inject advertisements into your redirects. The frustration of waking up to find hundreds of your carefully curated links now point to 404 pages is a scenario many have experienced.

Building your own URL shortener addresses these concerns while offering additional benefits. You gain complete data ownership, knowing exactly where your redirect mappings are stored and who has access to them. Customization becomes unlimited--you can implement custom slugs that match your branding, add analytics tracking, set expiration dates for temporary links, or integrate with your existing systems. The redirect logic runs on Cloudflare's global edge network, ensuring fast response times from locations close to your users worldwide.

Cloudflare Workers + KV storage provides an ideal foundation for this project. The generous free tier includes 100,000 requests per day, making it cost-effective for personal use or small teams. The edge deployment model means your shortener responds from over 200 data centers globally, delivering near-instant redirects regardless of user location.

For teams exploring serverless architectures, this URL shortener project demonstrates the power of edge computing. The same principles apply to larger systems where global distribution and automatic scaling are essential. Our cloud infrastructure services help organizations leverage these technologies for production workloads, while our web development expertise enables seamless integration with existing applications.

Understanding Workers KV

Workers KV is Cloudflare's distributed key-value store designed specifically for edge computing workloads. It provides low-latency access to data from any edge location, making it ideal for storing the URL mappings that power a shortener. When you store a key-value pair in KV, the data propagates to Cloudflare's global network, ensuring consistent access from any location.

The storage model is straightforward: you create namespaces that act as isolated containers for your data. Within a namespace, you store key-value pairs where the key is typically the short code (like "abc123") and the value is the destination URL. When a request comes in, your worker queries KV for the key, retrieves the value, and performs the redirect.

KV offers different consistency levels depending on your needs. The default eventually consistent model propagates writes across the network within about 60 seconds, which works well for most use cases. For applications requiring stronger consistency, you can configure namespaces for strong consistency, though this may impact write latency. For a URL shortener, eventual consistency is typically acceptable--links may take a minute to become globally available after creation.

Setting Up Your Development Environment

Before writing code, you'll need to set up your development environment with Cloudflare's official tooling. The Wrangler CLI is essential for managing Workers projects, deploying code, and interacting with KV namespaces from your terminal.

Begin by installing Wrangler globally via npm or yarn:

npm install -g wrangler
# or with yarn
yarn global add wrangler

After installation, authenticate with your Cloudflare account:

wrangler login

Initialize a new Workers project:

mkdir my-url-shortener
cd my-url-shortener
wrangler init

Creating KV Namespaces

Your URL shortener needs a place to store the mappings between short codes and destination URLs. Workers KV uses namespaces to organize data:

wrangler kv:namespace create SHORTLINKS
wrangler kv:namespace create SHORTLINKS --preview

Configure the namespaces in wrangler.toml:

kv_namespaces = [
 { binding = "SHORTLINKS", id = "prod-id", preview_id = "preview-id" }
]

This configuration tells Wrangler to make your KV namespace available to the worker code via env.SHORTLINKS. The binding name can be any valid identifier, but using SHORTLINKS makes the code self-documenting. For production deployments, consider setting up environment-specific configurations to manage staging and production environments separately, or explore our web development services for guidance on CI/CD pipeline integration.

Implementing Visit Tracking

Understanding how often your links are accessed provides valuable insights for marketing campaigns, content performance analysis, and usage monitoring. Implementing visit tracking stores access counts you can query later.

The basic approach stores visit counts in KV with a key format like stats:{shortCode}. On each redirect, increment the count asynchronously:

if (request.method === 'GET' && path) {
 const targetUrl = await env.SHORTLINKS.get(path);

 if (targetUrl) {
 const statsKey = `stats:${path}`;
 // Update stats asynchronously
 env.SHORTLINKS.get(statsKey).then(count => {
 const newCount = (parseInt(count) || 0) + 1;
 env.SHORTLINKS.put(statsKey, newCount.toString());
 });

 return Response.redirect(targetUrl, 301);
 }
}

Query visit counts via an endpoint:

if (path.startsWith('stats/')) {
 const shortCode = path.slice(6);
 const count = await env.SHORTLINKS.get(`stats:${shortCode}`);
 
 return new Response(JSON.stringify({
 shortCode,
 visits: parseInt(count) || 0
 }), { headers: { 'Content-Type': 'application/json' } });
}

As demonstrated in EastonDev's URL shortener guide, this approach efficiently tracks link access without impacting redirect performance. For teams requiring advanced SEO analytics, this tracking data can inform link-building strategies and content performance optimization.

Performance Optimization

Cloudflare Workers and KV are already performant by design, but several optimizations further improve response times. For web applications requiring optimal performance, our web development team can help you implement additional optimization strategies across your entire stack.

Caching Frequently Accessed Links

const cache = new Map();

if (request.method === 'GET' && path) {
 let targetUrl = cache.get(path);
 if (!targetUrl) {
 targetUrl = await env.SHORTLINKS.get(path);
 if (targetUrl) cache.set(path, targetUrl);
 }
 // ... redirect
}

Reducing KV Writes

The free tier allows 1,000 writes per day. Statistics tracking can consume this quota quickly. Consider:

• Writing statistics in batches
• Using different storage for analytics
• Implementing periodic aggregation

Deploying to Production

wrangler deploy

After deployment, your worker is accessible globally. Bind custom domains through the Cloudflare dashboard under Settings > Triggers > Custom Domains.

Following optimization strategies ensures your URL shortener performs efficiently at scale. For enterprise-grade deployments with additional caching needs, consider integrating Cloudflare's CDN capabilities or exploring our AI automation services for intelligent caching strategies.

R2 Integration for File Hosting

Beyond URL shortening, Cloudflare's R2 storage enables file hosting alongside your shortener. Create an R2 bucket and configure it for public access. Upload files and access them at https://your-bucket.r2.pages.dev/filename. Create KV entries mapping short codes to these R2 URLs to serve files through your shortener.

This integration extends your shortener from a pure redirect service to a comprehensive link management platform for sharing documents, images, or any file type. As demonstrated in Berkan Kütük's implementation guide, combining Workers, KV, and R2 creates a powerful solution for link and asset management. For organizations requiring comprehensive cloud storage solutions, R2 integration represents the beginning of a flexible infrastructure that grows with your needs.

Conclusion

Building a URL shortener with Cloudflare Workers combines modern edge computing capabilities with simple, effective storage. The implementation requires minimal code while delivering globally distributed, low-latency redirects. The platform handles scaling automatically, ensuring reliable performance as usage grows.

The features covered--from basic redirection through custom slugs, visit tracking, and access control--provide a foundation you can extend for specific needs. Whether you're sharing links on social media, managing marketing campaigns, or creating memorable URLs for personal projects, your self-hosted shortener gives you complete control.

This cloud-native approach represents how modern applications are increasingly built--decomposed into managed services that scale automatically and deploy globally. Our cloud infrastructure specialists can help you design and implement custom solutions tailored to your specific requirements, from serverless architectures to full-stack web applications using modern AI automation patterns. For organizations focused on SEO performance, proper link management and tracking are essential components of a comprehensive digital strategy.

Sources

1. LogRocket: Create a URL shortener with Cloudflare Workers
2. Thomas Levesque: Building a URL shortener in 12 lines of code
3. EastonDev: Building Your Own URL Shortener with Workers + KV Storage
4. Berkan Kütük: Personal URL Shortener with Cloudflare Workers, KV and R2
5. Cloudflare Workers Documentation
6. Cloudflare Workers KV Documentation