What is routing? (how URLs become pages)

What it actually is

Routing is the map between URLs and your app’s content. When someone opens /pricing, something has to decide what that address means, which page to render or which piece of backend code to run. That decision is routing. Think of the directory board in an office lobby: a visitor arrives with a name, and the board points them to a floor and a door. The URL is the name, the route is the entry on the board, and the page or API endpoint is the office behind the door.

Most modern frameworks use file-based routing, where the folder structure is the map. Put a file at src/pages/about.astro (Astro) or app/about/page.js (Next.js) and /about exists. There is no routing config to maintain; the file’s location is the address. Square brackets make a segment dynamic: app/blog/[slug]/page.js matches /blog/anything, and your code receives the value (slug: "anything"), so one file can serve a thousand blog posts.

There are two ways to move between routes once a site is open. Server-side navigation is the classic web: every click asks the server for a fresh HTML page. Client-side navigation is what single-page apps do: JavaScript intercepts the click, swaps components in place, and updates the address bar without a reload. It feels instant, and it sets up the one routing bug almost every vibe coder hits.

Why your AI just did this

Ask your agent for “a settings page” and it may not write any routing code at all. It creates a file in the right folder, the route appears, and its summary says something like “added a route at /settings.” The same convention often covers data: in Next.js, a file at app/api/posts/route.js becomes the /api/posts endpoint. So when your agent talks about routes, look at the file tree first; that is usually where the change happened.

Routing vocabulary also shows up when links break. “That route doesn’t exist yet” or “the dynamic segment doesn’t match” both mean the map and the address disagree. And if you’re building with plain React (no framework), your agent will bring in a router library such as React Router, because React itself ships without one.

When you’ll run into it

The famous one: everything works on localhost, you deploy, the app still works while you click around, then you refresh on /dashboard (or send someone that link) and get a 404. A single-page app ships one real HTML file, index.html, and the router runs in the browser’s JavaScript. Clicking your way to /dashboard works because JavaScript changed the view. Refreshing is a different request: the browser asks the server for /dashboard, the server looks for a file by that name, finds nothing, and answers 404. The route lives in JavaScript the server never runs.

Dev hid the bug because dev servers cover for you. Vite’s dev server, for example, runs in SPA mode by default (appType: 'spa') and answers unknown paths with index.html so the router can take over. Production hosts are stricter. The fix is a fallback rule that tells your host: for any path you don’t recognize, serve index.html and let the client-side router handle it. On Netlify that is one line in a _redirects file, /* /index.html 200. On Vercel it is a rewrite in vercel.json that sends every path to /index.html; Vercel’s Vite docs warn that deep links in a Vite single-page app won’t work until you add it. Cloudflare Pages assumes a single-page app when your build has no top-level 404.html and applies the fallback on its own. Hosts differ, so ask your agent for the rule that matches where you deploy.

Two more places you’ll meet routing: frameworks that render pages on the server (SSR or SSG) skip the refresh bug entirely, because the server knows every route and can answer any URL directly. And in dev, a typo’d folder name shows up as your framework’s built-in 404 page, which is routing telling you the map has no such entry.

What to check

• Refresh every page of your deployed app straight from the URL bar before you call a deploy done; clicking around only tests client-side navigation
• Read the app/ or pages/ folder when a URL misbehaves; the file tree is the route map, so a wrong folder name is a wrong URL
• Add your host’s SPA fallback rule if refreshing 404s in production (on Netlify: /* /index.html 200 in a _redirects file)
• Confirm dynamic segments line up: a folder named [id] hands your code a value called id, not slug
• Ask your agent whether pages render on the server or only in the browser; server-rendered apps don’t need the fallback

Say it like a dev

Instead of: “my app breaks when I refresh the page” Say: “My single-page app 404s on hard refresh in production. Add the host’s fallback rewrite so unknown paths serve index.html.”

Instead of: “I want another screen for settings” Say: “Add a /settings route with its own page component, using the framework’s file-based routing.”

Instead of: “some product links work and some don’t” Say: “The dynamic route /products/[id] isn’t matching every case. Check the segment name and the params the page receives.”