When people hear MCP, they often think of “just another API.” That shorthand might be convenient, but it misses the point.

MCP stands for Model Context Protocol. And the crucial word is Protocol.

Protocols define rules for how systems exchange data. They shape expectations, behavior, and guarantees. Treating MCP as “just an API” risks overlooking the major benefits it brings when integrating models with tools and services.

Protocols vs. APIs: A Quick Analogy

Think of two well-known protocols:

• FTP exists to move files. Narrow, explicit, and predictable.

• HTTP (Hypertext Transfer Protocol) is more flexible. It moves HTML, JSON, files, and more. It enables servers to expose arbitrary APIs, written in any language, with the server deciding what payloads it accepts and returns.

When we build HTTP servers, we define:

• What payloads are allowed

• How responses look

• What errors mean

MCP follows the same pattern — but with different goals and stricter constraints.

What MCP Servers Expose

Instead of arbitrary endpoints, MCP servers expose:

• Tools — well-defined capabilities a model can invoke

• Resources — structured data or state that the model can use

• Prompts — reusable instructions and contextual snippets

MCP clients (including model-driven agents) call these tools over a standardized protocol.

Because message types, action lifecycles, and behaviors are explicit, the runtime — not the model — handles coordination and guardrails.

Why MCP Is Stricter Than HTTP (and Why That’s Good)

MCP’s strictness is not a limitation. It’s the point.

It delivers real advantages:

• ✅ Safer interactions: formalized behaviors reduce hallucinations and unintended actions.

• ✅ Predictability: agents follow a clear contract instead of improvising ad hoc requests.

• ✅ Easier integration: validation, retries, and authorization can be enforced by tooling.

• ✅ Clear separation of concerns: models focus on intent; the protocol governs execution and context exchange.

In short:

• HTTP → HTTP servers → APIs for applications

• MCP → MCP servers → Tools for AI agents

Both are protocol + servers → exposed resources, but MCP is purpose-built for governing model behavior with tighter, safer rules.

When to Think in Terms of Protocols

If you’re building any of the following:

• 🛠️ Agent tooling

• 🔗 Orchestrations where LLMs call external services

• 📊 Integrations where models act on data or systems

...then designing around a protocol like MCP will:

• reduce complexity,

• increase reliability, and

• give you consistent behavior across models, clients, and runtimes.

Final Note

Protocols let you codify expectations once and reap benefits everywhere.

If you’ve built something interesting with MCP, share it! The ecosystem grows stronger with every experiment.

So I didn’t. I chose a Windows laptop, confident I could make it work. How hard could it be to set up a dev environment and find macOS alternatives?

Turns out, very hard.

For the next 1.5 years, I ran WSL 2, hunted down app alternatives, and built my own workflows from scratch. My setup worked, technically—but it came at a cost. I was constantly troubleshooting, Googling obscure errors, and navigating issues my teammates couldn’t help with because our systems were too different.

That extra friction showed up in my work. I had to regularly overestimate timelines just to give myself buffer for setup and workaround time. On paper, it made me look like a sluggish developer, consistently taking longer than average. My direct manager understood, but I knew it wasn't a good look with the higher-ups, as there was no easy way to communicate this up the chain.

You might wonder: once it’s all set up, doesn’t it get easier?

Partially, yes—but nothing stays still in tech. New, groundbreaking tools are introduced all the time, and our team’s processes were often updated to include them—always designed for macOS first. For me, that meant finding alternatives, getting them approved by IT and Security, and then starting my actual work. It was a never-ending treadmill of catch-up.

Eventually, I realized that my stubbornness was hurting my career more than it was helping my comfort. So, I switched to a MacBook.

I took a couple of weeks of official "training" to make it clear that I was learning a new platform. Immediately, the experience changed. When I ran into issues, teammates could actually help. I could dive into work instead of battling my setup.

My biggest lesson wasn’t about technology, but about trade-offs. Letting go of personal preferences isn’t a defeat; it’s about setting yourself up for success—and your team, too. Exploration and challenging the norm are important, but when you fight the current for too long, you risk drifting further from where you’re trying to go.

As I navigated through it, I asked a lot of questions in different Slack channels. One support person really stood out. He not only answered my questions in the channel but also DMed me to help debug issues. He was consistently helpful, patient, and made understanding their service much easier.

After finishing the task, I wanted to thank him publicly and looked him up — turns out, he’s an intern. That really stuck with me. Despite being early in his career, he showed strong communication, initiative, and technical skills.

I gave him a shoutout and messaged his manager, because honestly, he earned it. I learned how to make an early impression from him. If you’re an intern or early in your career, this is how you make a strong impression.

I built this little URL shortener for myself. Think of it as a personal version of something like dub.co, which lets me share short, memorable links instead of full URLs. For example, when I want to share my Linkedin profile, I can share "arpit.im/in" instead of remembering my Linkedin username, and the fact that Linkedin likes to add /in before the username (linkedin.com/in/arpitdalal) in their URL. Super convenient when sharing links or adding them to my resume! Plus, there's a hidden superpower: when I change usernames on various platforms (which happens more than I'd like to admit), I only need to update one redirect in my service rather than hunting down every instance of that link across the internet.

This humble URL router started its life as a traditional Node.js and Express app running happily on fly.io. It was comfortable, familiar territory. Until I decided to shake things up and migrate the whole thing to Cloudflare Workers using Bun and Hono.

Why would I abandon a perfectly functional setup for the wild west of edge computing? Well, that's where my adventure begins, and let me tell you – it's been quite the roller coaster ride!

Why I Jumped Ship

"Why mess with something that works?" Fair question! My Node.js and Express setup was solid and reliable, quick to build and easy to modify, despite the occasional TypeErrors that JavaScript loves to surprise you with.

Since I was planning to migrate to TypeScript anyway, I figured this was the perfect opportunity to expand my horizons. Why just add types when I could learn something completely new in the process?

I initially chose the familiar stack to ship quickly (a decision we've all made). But once my project was live and stable, I couldn't ignore that developer urge to evolve it into something more, to actually learn from this little side project instead of letting it stagnate.

That’s when Hono caught my eye because it has a similar API to Express (which is pretty robust), but it's supposedly "blazingly fast" and comes with native TypeScript support. Win-win!

Life got busy (as it does), and a couple of months flew by. When I finally circled back to this idea, I thought, "Why stop at just changing the framework? Let's go all in and try a new runtime too!"

I was torn between Deno, Bun, and Cloudflare's workerd. This was my first deep dive into CF Workers, and what really blew me away was learning they run on V8 Isolates with practically zero cold-start time.

That last point was a game-changer! AWS Lambdas and its different flavours from Netlify or Vercel have pretty noticeable cold-starts. That’s why I chose a long-running server on fly.io to avoid those painfully slow serverless cold-starts. Nobody wants to wait ages for a simple redirection, right? Plus, Cloudflare's edge network meant my app would run in multiple regions worldwide, not just from my lonely fly.io server in Toronto.

I'd been using npm as my package manager for ages, but kept hearing about faster alternatives. The benchmarks for pnpm and bun looked impressive, and I was curious. I ultimately went with bun, partly for the speed, but mostly because I wanted to experiment with their cutting-edge approach to JavaScript tooling.

So that settled it - Hono as the framework, Bun for the tooling, and Cloudflare Workers as the infrastructure. Time to jump in!

The Good Stuff (aka Why I Don't Completely Regret My Decision)

Amazing Community Support - The Hono community absolutely loves Cloudflare Workers, which meant there were tons of starter guides and examples. This saved me hours of head-scratching!

Documentation That Doesn't Make You Cry - Refreshingly, Hono's docs for Cloudflare Workers integration are actually current and comprehensive. It's rare to find such well-maintained documentation when one tool integrates with another. I didn't need to waste hours digging through GitHub issues or outdated guides to get things working, the answers were right there in the docs.

Surprisingly Good Library Support - The Cloudflare Workers ecosystem surprised me with its maturity, far more libraries offer native support than I expected. From testing to rate limiting, I found packages for most common needs without having to build workarounds.

Super Simple Local Development - Setting up my local development environment was remarkably smooth. The community starter templates combined with wrangler's local dev server had me coding productively within minutes, not hours, which is a welcome change from my previous serverless experiences.

Testing That Doesn't Suck - Testing with Hono turned out to be surprisingly pleasant. Cloudflare's vitest plugin effectively simulated the production environment in my test suite, eliminating those frustrating "works locally, fails in production" moments that plague serverless development.

The Not-So-Good Stuff (aka The Parts That Made Me Question My Life Choices)

Cloudflare Dashboard: The Labyrinth - Is it just me, or is the Cloudflare dashboard intentionally designed to confuse people? I spent more time than I'd like to admit just trying to find the right settings.

Domain Setup From Hell - To serve my worker on a custom domain, I had to change my nameservers to Cloudflare. This seemingly simple change took my domain down for over HALF A DAY. The more baffling thing is that I have no idea why it took that long and there’s no way for me to expedite it or fix it. Not exactly what I'd call a smooth transition!

Wrangler: Powerful but Mysterious - Wrangler (Cloudflare's CLI tool) is incredibly powerful, but it's also incredibly confusing. The learning curve is steeper than it needs to be. Maybe it’s a skill issue?

Wrangler Config Nightmare - Cloudflare forces you to stuff everything into wrangler.jsonc/.toml files: environment variables, domain zone IDs, KV store configs… you name it! This creates an immediate security dilemma: how do I version control the wrangler config file without exposing my secrets on GitHub? I wasted countless hours putting together a secure CI/CD pipeline. My "solution"? Storing secrets in GitHub Actions and using scripts to dynamically replace placeholders in the wrangler config during deployment. It works, but feels like a clunky workaround for what should be a solved problem. While Netlify and Vercel elegantly separate configuration from secrets through an intuitive dashboard, Cloudflare's approach feels like it was designed by people who've never had to manage a production deployment pipeline for an open source project.

Mysterious Versioning System - Instead of using sensible semantic versioning like every other tool in the JavaScript ecosystem, Cloudflare decided to implement "compatibility dates" in wrangler configs that magically change available types and behaviors. Change one date and suddenly your TypeScript throws errors because APIs have different signatures? Fun times! I still don't fully understand the reasoning behind this approach - there's a reason npm package versions exist and are universally adopted. This unconventional system makes it unnecessarily difficult to predict how your code will behave across environments or when upgrading.

Too Much Magic, Not Enough Explanation - Some types are just magically available in the workerd environment, which becomes a real headache when your tests are running in a non-workerd environment.

Debugging in the Dark - Since it's not a long-running server, debugging when something goes wrong can feel like trying to find a specific snowflake in a blizzard.

What I Learned From All This

Would I recommend Cloudflare Workers? Yes, but know what you're getting into.

Despite all my griping, I don't regret making the switch. My links now load noticeably faster thanks to Cloudflare's global edge network - when someone clicks my URL in Australia, they're not waiting for a server in Toronto to respond. Yes, I traded my zero-cold-start setup for occasional millisecond delays, but they're so minimal that neither I nor my users can detect them. The unexpected bonus? Cloudflare's built-in bot protection system. My old setup would occasionally get hammered by random bots, causing unexpected spikes and headaches. Now I sleep better knowing there's an enterprise-grade security system standing guard over my humble little URL shortener. The migration headaches were real, but for my specific use case, the benefits have outweighed the costs.

That said, if I could do it again, I would spend more time upfront understanding Cloudflare's ecosystem before diving in. Their approach is fundamentally different from traditional servers, and that requires a mental shift.

For anyone considering a similar move, my advice would be: spend some time to understand how CF works, start with a small project, expect some frustration with the config and deployment process, but stick with it because the performance and security benefits from Node.js are worth it in the end.

Here’s the before and after diff for my project.

Have you tried Cloudflare Workers or similar edge computing platforms? Was any of this a skill issue? I'd love to hear about your experiences and how you overcame similar challenges!

Introduction

Analytics are crucial for understanding user behavior resulting in better products and higher user satisfaction. But, sometimes these analytics tools are blocked by adblockers. This article explains how to ensure that analytics data is collected reliably while respecting user privacy.

PostHog is an excellent tool for web/product analytics, session replays, feature flags, A/B testing, and much more. It's also quite cheap compared to alternatives in this space.

The Problem

The main issue with analytics tools like PostHog is that they get blocked by adblockers, which results in the loss of valuable data.

The Solution: A Backend Proxy

This can be solved by setting up a reverse proxy in the backend that forwards analytics events to PostHog, bypassing adblockers completely. While this guide shows implementation with Remix/react-router, the same concepts apply to any modern JS framework.

Note: PostHog has official Remix integration docs but in my experience it doesn’t work as is, I had to tweak some things to make it work.

How it works

The proxy works by redirecting analytics traffic through the server:

1. Instead of the browser sending analytics directly to PostHog servers (where they can be blocked): Browser → PostHog (❌ blocked by adblockers)

2. The traffic can be routed through the server first: Browser → Server → PostHog (✅ not blocked)

This simple redirection makes adblockers ineffective against the analytics collection.

Implementation Steps

1. Create the endpoint

First, create an endpoint that won't trigger adblockers. It's recommended to avoid names like "analytics" or "posthog”. Instead, use something generic like /resources/ingest.

Create a file named ingest.$.tsx under app/routes/resources. The $ creates a catch-all route that will handle all PostHog endpoints like /resources/ingest/e, /resources/ingest/decide, etc. Official react-router docs call these Splat routes.

The splat route is essential here because PostHog's SDK sends requests to multiple endpoints. Using a catch-all route allows us to handle all these different PostHog endpoints with a single file rather than creating separate handlers for each one.

2. Set up constants

const API_HOST = "us.i.posthog.com"; // use eu.i.posthog.com for EU
const ASSET_HOST = "us-assets.i.posthog.com"; // use eu-assets.i.posthog.com for EU

type RequestInitWithDuplex = RequestInit & {
  duplex?: "half"; // https://github.com/microsoft/TypeScript-DOM-lib-generator/issues/1483
};

These constants define which PostHog servers to connect to. The custom type RequestInitWithDuplex adds the duplex property needed for handling larger POST requests properly.

The duplex: 'half' property is necessary when working with request bodies in a streaming context. It tells the fetch API that the server will only be reading from the stream (not writing to it), which is important for properly handling PostHog's data payloads, especially larger ones.

3. Create the proxy function

async function posthogProxy(request: Request) {
  const url = new URL(request.url);

  // Choose the right host based on the request path
  const hostname = url.pathname.startsWith("/resources/ingest/static")
    ? ASSET_HOST
    : API_HOST;

  // Build the new URL to forward to PostHog
  const newUrl = new URL(url);
  newUrl.protocol = "https";
  newUrl.hostname = hostname;
  newUrl.port = "443";
  newUrl.pathname = newUrl.pathname.replace(/^\/resources\/ingest/, "");
  //                                        ^ depends on the endpoint

  // Prepare headers
  const headers = new Headers(request.headers);
  headers.set("host", hostname);
  headers.delete("accept-encoding"); // to let the fetch handle compression

  // Setup fetch options
  const fetchOptions: RequestInitWithDuplex = {
    method: request.method,
    headers,
    redirect: "follow", // enable fetch to follow the redirect in case PostHog throws a redirect
  };

  // Add body for non-GET/HEAD requests
  if (!["GET", "HEAD"].includes(request.method)) {
    fetchOptions.body = request.body;
    fetchOptions.duplex = "half"; // needed for larger POST bodies
  }

  try {
    // Forward the request to PostHog
    const response = await fetch(newUrl, fetchOptions);

    // Clean up response headers
    const responseHeaders = new Headers(response.headers);
    responseHeaders.delete("content-encoding");
    responseHeaders.delete("content-length");
    responseHeaders.delete("transfer-encoding");
    responseHeaders.delete("Content-Length");

    // Get response data if needed
    const data =
      response.status === 304 || response.status === 204
        ? null
        : await response.arrayBuffer();

    // Return the response
    return new Response(data, {
      status: response.status,
      statusText: response.statusText,
      headers: responseHeaders,
    });
  } catch (error) {
    // Track and log the error
    console.error("Proxy error:", error);
    return new Response("Proxy Error", { status: 500 });
  }
}

This function:

• Determines which PostHog host to use based on the request path

• Constructs a new URL with the correct host and modified path

• Sets up the proper headers for the proxied request

• Handles the request body for non-GET/HEAD methods

• Makes the fetch request to PostHog

• Cleans up the response headers to avoid encoding issues

• Returns the proxied response or handles any errors

4. Set up the loader and action

import { type LoaderFunctionArgs, type ActionFunctionArgs } from 'react-router'

export async function loader({ request }: LoaderFunctionArgs) {
  return await posthogProxy(request);
}

export async function action({ request }: ActionFunctionArgs) {
  return await posthogProxy(request);
}

In Remix/react-router, the loader function handles GET/HEAD requests, while the action function handles all other HTTP methods (POST, PUT, DELETE, etc.). Both functions simply call the posthogProxy function created earlier.

5. Configuring the PostHog Client

Once the proxy is set up, the PostHog client needs to be configured to use it:

posthog.init('<YOUR_API_KEY>', {
  api_host: '/resources/ingest' // point to the proxy endpoint instead of PostHog's servers
  ui_host: 'https://us.posthog.com', // use https://eu.posthog.com for EU
  // ^ Necessary when using reverse proxy - https://posthog.com/docs/libraries/js#config
})

Troubleshooting

Here are some common issues one might encounter:

1. CORS errors: If there are CORS-related errors, ensure the server is properly handling OPTIONS requests and forwarding the appropriate headers.

2. Missing data: Check the browser's Network tab to see if requests to the proxy endpoint are succeeding with 200 status codes.

3. Encoding issues: If there are any corrupted data or encoding errors, make sure the response headers are properly handled as shown in the proxy function.

4. Feature flags not working: Feature flags require the /decide endpoint to work properly. Verify that requests to this endpoint are being correctly proxied.

Why This Matters

With this reverse proxy in place, analytics data will flow to PostHog even when users have adblockers enabled. This gives more accurate insights into how people are using products and helps make better data-driven decisions.

For the complete code, check out this gist.

For other frameworks or providers, see PostHog's official proxy documentation.

At this point, you've likely heard of AI products like GitHub Copilot, Cursor, and Devin. If not, it's worth understanding what these different products offer, especially as Devin has just launched publicly for USD 500 per month for a seat, generating both excitement and concern across the tech industry.

As companies invest heavily in AI development tools, understanding these different approaches becomes crucial for developers and businesses alike. Let's explore how these approaches are shaping the future of coding.

The Fundamental Difference: Teammate vs Companion

To understand the impact of these tools, we first need to examine their fundamental differences in approach and implementation.

Positioning and Marketing

• Devin markets itself as a "teammate" and "junior developer," suggesting an autonomous role

• GitHub Copilot and Cursor position themselves as "companions", integrating directly into your development workflow

Usage Patterns

These different positioning strategies are reflected in how these tools are actually used in practice, with stark contrasts in their operation, target users, and pricing models.

Devin: The Autonomous Agent

1. Operation

   • Operates independently through Slack or GitHub

   • Makes its own coding decisions and creates pull requests

   • Cannot assist with real-time coding; works as a standalone developer

2. Cost & Target Audience

   • Target audience appears to be non-technical stakeholders like product owners and project managers

   • Enables communication through familiar platforms (Slack, GitHub) for non-developers

   • Costs USD 500 per month for a seat

Copilot & Cursor: The Developer's Assistant

1. Operation

   • Integrated directly into IDEs/editors

   • Developer maintains control over architectural decisions

   • Assists with autocomplete, refactoring, and feature creation

2. Cost & Target Audience

   • Focuses on enhancing developer productivity rather than replacement

   • Usually costs around USD 10 to 20 per month for a seat

A Personal Experience: Working with AI Companions

To illustrate these differences in practice, let me share a recent experience…

I recently worked on a React Native app where I needed to refactor several similar screen components. Using Claude 3.5 Sonnet via Cursor, I experienced firsthand how these companion tools enhance developer workflow:

1. Initial refactoring attempt produced a good but rigid abstraction

2. Requested customization led to an overcomplicated API

3. Finally guided it to create a composable component architecture, resulting in an elegant solution. I documented the before and after code transformation on X

The key insight here is: While the AI wrote the code, I made the architectural decisions, demonstrating the ideal companion relationship.

Review of Devin

While my experience focuses on AI companions, let's examine how Devin performs as an autonomous agent.

I haven't personally tested Devin, but Steve from builder.io recently shared a comprehensive hands-on review that provides valuable insights into its capabilities. His demonstration highlights both Devin's strengths and limitations in real-world development scenarios.

Steve's review (linked below) showcases:

• How Devin interacts with development tasks

• Where it excels compared to traditional coding companions

• Current limitations and areas for improvement

The main takeaway from Steve's review is clear: while Devin shows promise as an autonomous agent, it currently falls short both as a developer replacement and as a practical tool for existing development teams.

While Devin's current limitations are apparent, its emergence and the market's response to it reveal broader implications for the future of software development.

Market Impact and Future Implications

Current State

The emergence of Devin signals the birth of a new category in software development: autonomous development agents that aim to replace human developers. Cognition AI, the company behind Devin, has achieved a USD 2 billion valuation based on its ambitious goal: creating the first AI tool capable of replacing human developers. This valuation suggests strong confidence in this direction, but the current reality presents significant challenges:

• Limited ability to follow complex instructions accurately

• The relatively high cost of USD 500 per month restricts widespread adoption considering it cannot replace a human developer yet

• Inconsistent output quality compared to human developers

• Architectural decisions often require human intervention

While these challenges are significant, looking ahead reveals how these tools might reshape the development landscape.

Future Trajectory and Industry Impact

The implications of tools like Devin extend beyond their current capabilities:

1. Developer Stratification

   • Lower-productivity developers may face increasing pressure from autonomous AI tools

   • The role of developers may evolve to focus more on system architecture and AI oversight

   • Teams might restructure around AI capabilities, with humans focusing on high-level decision-making

2. Adaptation and Evolution

   • Developers who effectively integrate AI tools into their workflow will likely thrive

   • The focus may shift from coding proficiency to AI collaboration skills

   • New roles might emerge at the intersection of development and AI operations

3. Market Transformation

   • The success of early autonomous agents could accelerate investment in this space

   • Traditional development tools may evolve to include more autonomous features

   • The definition of "developer productivity" may need to be reconsidered

This transition suggests not a wholesale replacement of developers, but rather a redistribution of skills and responsibilities in the development ecosystem. Success in this new landscape will likely depend on adapting to and leveraging these emerging technologies rather than competing against them.

Conclusion

While GitHub Copilot and Cursor excel at enhancing developer productivity through collaboration and can produce high-quality code, they ultimately rely on human developers for architectural decisions and system design. Devin represents an ambitious attempt to cross this frontier, aiming to create truly autonomous development capabilities. However, despite its bold vision and Cognition AI's significant market valuation, Devin's current capabilities fall short of this goal. This fundamental difference in approach - companion vs teammate - reflects a broader industry shift toward AI integration in software development, with each type of tool serving distinct audiences and use cases. As these technologies evolve, the question remains: will AI tools continue to complement human developers, or will they eventually achieve the level of autonomy that Devin aspires to?

Introduction: Understanding the Power of URLs

What is a URL?

Think of a website like a house: you need an address to reach there. Whether you arrive via GPS (search engines), someone's directions (links), or knowing the address by heart (direct URL), you still need that unique location identifier. The browser's address bar serves exactly this purpose, providing direct access to any resource on the web.

To understand URL structure better, visit howurls.work. In this article, we'll focus specifically on the path component and how thoughtful URL design can enhance user experience.

Why does the path matter?

It doesn’t… to most people using the internet. But to the power users, it’s the way they might access a resource on the server. For example, if you visit arpitdalal.dev/me, you’ll land on my about page. Here, you accessed the me resource on the server where my website is hosted.

That was easy, but let’s take this example to access different repositories and different parts of those repositories on GitHub. On GitHub, every repository has to have an owner account or an owner organization. In the case of github.com/arpitdalal/arpitdalal.dev, arpitdalal is the owner and arpitdalal.dev is the repository. For github.com/remix-run/remix, remix-run is the organization and remix is the repository. You can also directly access the commits on that repository by adding /commits to the URL, github.com/remix-run/remix/commits. Also, individual commits can be accessed like so github.com/remix-run/remix/commit/66bb870c17a4d778a3cff66973fee5314c694f82.

Every page/resource can be accessed via path in a URL.

What does it have to do with Notion?

Notion is built with power users in mind, so they architected their URLs in a really clever way.

In the earlier example of Remix’s individual commit URL on GitHub, could you have guessed what that commit was about? It’s unlikely. The gibberish after /commit/ is an id that GitHub uses to know which commit to show, but it doesn’t help us to understand what the commit is about.

Now if I show you this URL

arpitdalal.notion.site/Arpit-Dalal-115f0f16d2cd80ea8cf0d37ffb8ccfdf

You’ll instantly know that you’re going to a custom Notion site, but read the full path of the URL Arpit-Dalal-115f0f16d2cd80ea8cf0d37ffb8ccfdf. It also has some gibberish but it has Arpit-Dalal in front of that gibberish.

How about this URL?

arpitdalal.notion.site/About-Arpit-Dalal-115f0f16d2cd8029b92ae679687607dd

The path here has About-Arpit-Dalal before the gibberish. Just by reading that you understand that the page has to be about… well… Arpit Dalal.

What if you type this URL in your browser? You get autocomplete on path of the URL that you’re trying to access. By only typing Abo, I already see a suggestion for About-Arpit-Dalal page.

Now imagine trying to access a commit from your project on GitHub, would that be possible? I don’t think so. But, Notion architected their URL paths in a way that the id used internally to identify pages doesn’t really matter when accessing those pages directly through a browser’s address bar.

Implementation: Building Notion-Style URLs

How do these URLs work?

That is a good question. While the exact implementation details aren't public, we can implement it in our own way.

This section will demonstrate a simple app that shows all the posts on the / path and each post details page on /{slug-id} path.

This example uses remix.run to create this app but this URL architecture can be built using any language or framework of your choice.

The Intrinsics

Rather than showing the full application setup, we’ll implement the necessary code to build this architecture.

We’ll first need a function that takes title and id of the post. Then, replace anything other than characters and numbers from the title with a - and then append the id after a - too. There we have the title’s slug prepended to the id.

function getSlugWithId({ title, id }: { title: string; id: string }) {
  // Validate inputs
  if (!title || !id) {
    throw new Error("Title and ID are required");
  }


  const slugifiedTitle = title
    .trim() // Trim the title for any leading/trailing spaces
    .replace(/[^a-zA-Z0-9]+/g, "-") // Replace special characters and spaces with hyphens
    .replace(/^-+|-+$/g, ""); // Trim any leading/trailing hyphens
    // You can lowercase the title too
    // I chose not to, to stay in parity with Notion's approach

  // Ensure we have valid content before creating slug
  if (!slugifiedTitle) {
    return id; // Fallback to just ID if title produces empty slug
  }

  return `${slugifiedTitle}-${id}`;
}

How to use it?

First, we need to show a link with slug-id for each post to the users. Let’s assume we’re getting the posts from a database as postsData. Then, we’ll need to replace the id with slug-id using our function getSlugWithId.

const posts = postsData.map((post) => ({
  ...post,
  id: getSlugWithId(post),
}));

We can show this data using React but you can choose to show it however you want. post here is a single post object containing title and id.

<Link to={`/${post.id}`}>
  <h2>{post.title}</h2>
</Link>

Now that users can go to the post details page /First-Post-aabbccddeeff, we need to retrieve the post details using this id.

Most frameworks will allow you to define dynamic routes, for Remix, the syntax is $postId.tsx. This will ensure that the dynamic value is named postId and can be accessed using params object passed in the loader. You can read more about it on Remix docs.

We have the post id First-Post-aabbccddeeff but we cannot search a post using it as the database doesn’t have slug-id. To remove the slug part from it, we can split the string with - and access the last part of it to retrieve the actual id.

function extractPostId(slugOrId: string): string {
  // Validate input
  if (!slugOrId) {
    throw new Error("Invalid post identifier");
  }

  // Split the slug-id combination
  const parts = slugOrId.split("-");
  const id = parts.at(-1);

  // Validate that we got a valid ID
  if (!id || id.length < 1) {
    throw new Error("Invalid post ID format");
  }

  // Optional: Add validation for expected ID format
  // For example, if IDs should be 12 characters
  if (!/^[a-f0-9]{12}$/.test(id)) {
    throw new Error("Invalid post ID format");
  }

  return id;
}

// Usage
try {
  const postIdRaw = params.postId;
  const postId = extractPostId(postIdRaw);
} catch (error) {
  // Handle error appropriately
  throw new Response("Invalid Post ID", { status: 400 });
}

The split("-").at(-1) method handles both new slug-id URLs and legacy URLs that contain only the id, maintaining backward compatibility. But the split("-") will return our id as the only item in an array if it doesn’t find the separator -, and since there’s only 1 item in the array, at(-1) will give us our id which means we are good on that front too.

Now it’s pretty easy to do a query against your database to find a post with this id and show it to your users.

Using these building blocks, we are able to prepend slug to the id, show it to the users in a link, retrieve it, and separate the slug from the id to retrieve more details. This way, the database stays clean of the slug and only has to care about id and we achieve an amazing UX for the power users who like to access their posts directly from the address bar.

That’s it… is it?

The core functionality is done, but we can improve the UX further by forcing a refresh when a user lands on the post details page without a slug. This will tell their browser that the URL without the slug has been moved to the URL with the slug.

We can easily achieve this by checking if the received postId has a - in it or not. We can rely on this simple check because even if the slug was only 1 word, we’d have a - to separate slug from id like so first-aabbccddeeff.
We already have the id that our database understands so we can directly search it and retrieve its title. Then, we can simply redirect the user to what we receive from our getSlugWithId function.

// Check if we need to redirect
if (!postIdRaw.includes("-")) {
  // Attempt to fetch post details
  const post = getPostById(postIdRaw);

  if (!post) {
    throw new Response("Post not found", {
      status: 404,
      statusText: "Not Found",
    });
  }

  // Generate new slug and redirect
  const newSlug = getSlugWithId(post);

  // Check if the new slug is different
  if (newSlug !== postIdRaw) {
    return redirect(`/${newSlug}`);
  }
}

Conclusion: Elevating User Experience with Smart URL Design

In conclusion, we explored the impact of URL architecture on user experience. By examining Notion’s approach to URL design, we determined incorporating meaningful slugs alongside ids can improve accessibility and usability for power users. We implemented the Notion-like URL architecture that supports both slug-id and just id in the path part of the URL which increases the user experience. This approach not only maintains a clean database structure but also provides a seamless and intuitive navigation experience for users. The demonstration of this architecture highlights its potential to enhance how users interact with web applications, making it a valuable consideration for developers aiming to provide a remarkable user experience.

You can find the complete code for this demo app on my GitHub or play with the code directly on StackBlitz.