Why Redirect Management is Critical for Developer Portals

Dec 18, 2025 - 7 min read

Joaquin Romo

Redirects are one of those infrastructure pieces you don’t think about until you need them. I’ve worked with them in two different contexts: a large-scale developer portal using Netlify with complex wildcard patterns and catch-all rules, and now this personal portfolio site on Vercel where I just implemented my first redirect after renaming a directory.

What struck me is how different platforms handle the same fundamental problem—keeping URLs stable when content moves—but with vastly different syntax and approaches. Whether you’re managing hundreds of versioned documentation pages or just reorganizing a small site, the principles remain the same.

Why URLs Break (and Why It Matters)

Content evolves. Files get renamed, directories get reorganized, documentation gets restructured. Every change risks breaking URLs that someone, somewhere, has bookmarked, shared, or embedded.

On this site, I recently merged two sparse sections—frameworks and tools—into a single frameworks-and-tools directory. Simple change, but any existing links to /frameworks/* would now return 404s. On a larger developer portal, these changes happen constantly: version branches, content restructures, product renamings.

The impact differs by scale:

• Small sites: Broken bookmarks, lost SEO ranking
• Developer portals: Broken Stack Overflow answers, tutorial videos with dead links, CI/CD scripts that can’t fetch docs
• Any site: Lost trust when links don’t work

A broken documentation link isn’t just bad UX—it’s a broken promise.

Two Projects, Two Approaches

This Site: Simple Structural Change on Vercel

After consolidating my frameworks and tools sections, I needed one redirect rule in vercel.json:

{
  "redirects": [
    {
      "source": "/frameworks/:path*",
      "destination": "/frameworks-and-tools/:path*",
      "permanent": true
    }
  ]
}

That’s it. Vercel’s syntax is JSON-based, uses :path* for wildcards, and permanent: true for 301 redirects. Deploy and done.

Enterprise Developer Portal: Complex Version Management on Netlify

At work, the redirect needs are more complex. Managing multiple documentation versions requires wildcard patterns and catch-all rules in netlify.toml:

Version redirects:

[[redirects]]
from = "/docs/v2.12/*"
to = "/docs/current/:splat"
status = 302

Catch-all for SPA routing:

[[redirects]]
from = "/docs/api/v2.11/*"
to = "/docs/api/v2.11/:splat"
status = 200

Global fallback:

[[redirects]]
from = "/docs/api/*"
to = "/docs/api/current/:splat"

Netlify uses TOML configuration, :splat instead of :path*, and supports status 200 rewrites for single-page applications. The syntax differs, but the goal is the same: keep URLs working.

Platform Differences: Same Goal, Different Syntax

Here’s what I learned working across both platforms:

Vercel (JSON)

• Configuration: vercel.json in repository root
• Wildcard: :path* captures remaining path segments
• Status codes: permanent: true (301) or permanent: false (302)
• Best for: Simple redirects, modern frameworks, multiple wildcards per rule

Netlify (TOML)

• Configuration: netlify.toml in repository root
• Wildcard: :splat captures remaining path segments
• Status codes: Explicit status = 301/302/200
• Special feature: Status 200 rewrites (serve different content without changing URL)
• Limitation: One wildcard per rule
• Best for: Complex versioned docs, SPA routing with rewrites

The Common Patterns

Despite syntax differences, redirect strategies are universal:

1. Wildcard redirects - One rule handles entire directory trees
2. Permanent (301) vs Temporary (302) - Choose based on whether the change is forever
3. Catch-all patterns - Fallback rules prevent 404s
4. Order matters - Most platforms process rules sequentially, first match wins
5. Version control - Both platforms treat redirects as code, reviewed in pull requests

Practical Lessons from Both Projects

1. Redirects Are Infrastructure, Not Afterthoughts

For this site, I created the redirect rule in the same commit as the directory rename. At work, redirect configuration lives in version control alongside content—every pull request that changes URLs includes the corresponding redirect rules.

This treats redirects as first-class infrastructure:

project-repo/
├── src/content/
├── vercel.json     ← Vercel redirects
└── netlify.toml    ← Or Netlify redirects

2. Order Matters: Specific Before General

Redirect platforms process rules sequentially—first match wins. This is critical for catch-all patterns:

Wrong order (catch-all first):

# This will match everything, specific rules never trigger
[[redirects]]
from = "/docs/*"
to = "/docs/current/:splat"

[[redirects]]
from = "/docs/old-guide"
to = "/docs/new-guide"  # Never reached!

Correct order (specific first):

[[redirects]]
from = "/docs/old-guide"
to = "/docs/new-guide"  # Matches first

[[redirects]]
from = "/docs/*"
to = "/docs/current/:splat"  # Catches everything else

3. Choose the Right Status Code

• 301 (Permanent): I used this for my directory rename—it’s permanent
• 302 (Temporary): Better for version aliases that might change
• 200 (Rewrite): Netlify-specific, for SPA routing without changing browser URL

The status code tells search engines whether to update their indexes (301) or keep the original URL (302).

4. Test Before Production

Both Vercel and Netlify offer deploy previews—every PR gets a preview URL to test redirects before merging. Essential for catching issues early.

5. Documentation Helps Future You

When I implemented my redirect, I referenced our comprehensive technical guide. Six months from now, I won’t remember the syntax differences between :splat and :path*—but the documentation will still be there.

Choosing the Right Platform for Redirect Management

Different hosting platforms handle redirects differently. The platform I work with uses file-based configuration that lives in version control alongside the documentation source. This approach fits naturally into docs-as-code workflows:

• Configuration as code: Redirect rules are reviewed in pull requests like any other change
• Deploy preview testing: Test redirects before they reach production
• No server management: Focus on documentation, not infrastructure maintenance
• Readable syntax: Technical writers can understand and modify redirect rules

Other platforms offer different tradeoffs—more powerful regex capabilities, multiple wildcards per rule, or programmatic control through serverless functions. The “best” platform depends on your specific needs:

• Simple docs-as-code workflow? File-based configuration platforms (Netlify, Vercel) work well
• Complex pattern matching needs? Traditional servers (Apache/Nginx) offer full regex power
• High-scale distributed systems? Cloud solutions (AWS CloudFront/Lambda@Edge) provide programmability

The key is choosing a platform that matches your team’s workflow and technical capabilities, not necessarily the most feature-rich option.

📚 Want the technical details? Check out our comprehensive Redirect Configuration Guide comparing syntax, features, and implementation across platforms.

What Good Redirects Enable

Whether managing a small portfolio site or a large developer portal, redirects provide the same benefits:

• Restructure confidently - reorganize content without worrying about breaking bookmarks or SEO
• Iterate faster - make improvements without coordinating with everyone who’s linked to your content
• Maintain trust - users land on the right page, even from years-old links
• Sustainable growth - sites can evolve without accumulating technical debt from fear of breaking URLs
• True docs-as-code - content changes flow through Git with redirect rules reviewed like any other code

Key Takeaways for Developer Portal Teams

If you’re building or migrating a developer portal, treat redirects as critical infrastructure:

1. Plan redirects before restructuring - don’t wait until after migration
2. Version control your redirect config - redirects are code, not server config
3. Use wildcard patterns - one rule can handle hundreds of URLs
4. Implement catch-alls - ensure users never hit 404s
5. Test in preview environments - catch problems before production
6. Monitor redirect metrics - 404 rates, redirect hits, chains
7. Choose platforms that support docs-as-code - file-based config beats UI-based config
8. Document your redirect strategy - future team members will thank you

Final Thoughts

Redirect management isn’t glamorous work. It’s invisible when it works correctly—which is exactly the point. Users shouldn’t think about redirects. They should just land where they need to go, regardless of which old URL they clicked.

The platforms differ—Vercel’s JSON vs Netlify’s TOML, :path* vs :splat—but the principles are universal. Whether you’re redirecting one renamed directory or managing hundreds of versioned documentation pages, the strategy remains the same: keep URLs stable, handle changes gracefully, and treat redirects as infrastructure.

I just implemented my first redirect on this site. At work, I work with complex multi-version redirect strategies. Both serve the same fundamental purpose: keeping promises to users who depend on links working.

---

Building a developer portal or migrating documentation platforms? I’d love to hear about your redirect challenges and strategies. Connect with me on LinkedIn to continue the conversation.

Tags:

• developer-portals
• redirects
• docs-as-code
• content-strategy
• url-management
• netlify

Building a GitHub Contribution Graph with Next.js Server Components

From Chaos to Clarity: A Technical Writer's Journey Through Git Cherry-Picking and Team Collaboration