Fighting with Redirects: A Journey of Astro Site Migration

During the migration of a website to Astro, I encountered significant challenges with URL redirects, particularly when dealing with Cloudflare Pages and Google Search Console. This article details the technical hurdles and solutions discovered while implementing redirects for a site with over 1000 legacy URLs.

Technical Context

• Framework: Astro
• Hosting: Cloudflare Pages
• Tools: Google Search Console
• Key File: _redirects configuration

The Problem

After migrating from WordPress to Astro, I needed to redirect numerous URLs from the old structure /blog/post/[slug] to the new structure /post/[slug]. While this seems straightforward, the implementation revealed several complexities:

1. Inconsistent behavior with trailing slashes
2. Wildcard matching limitations
3. Cloudflare Pages' specific redirect rules
4. Caching issues affecting redirect testing

Different Approaches Tried

1. Using Wildcards

Initial attempt using wildcards:

/blog/post/*  /post/:splat  301

This approach failed because:

• URLs with trailing slashes were redirected to /post/*/
• The 301 status code caused unexpected behavior

2. Using Path Parameters

Second attempt using path parameters:

/blog/post/:slug  /post/:slug

This partially worked:

• /blog/post/005 correctly redirected to /post/005/
• /blog/post/005/ incorrectly redirected to /post/*/

3. Combined Approach

Attempted to handle both cases:

/blog/post/:slug /post/:slug
/blog/post/:slug/:page /post/:slug/:page
/blog/post/* /post/:splats

This still didn't provide consistent behavior across all URL patterns.

The Solution

After experimenting with various patterns and configurations, the most reliable solution was to explicitly list each redirect:

/blog/post/article-1 /post/article-1
/blog/post/article-2 /post/article-2
# ... and so on

While this approach might seem less elegant than using wildcards or parameters, it provides:

1. Predictable behavior
2. Easy troubleshooting
3. Clear mapping for Google Search Console
4. No issues with trailing slashes

Key Learnings

1. URL Pattern Matching Complexity:

   • Wildcards (*) and path parameters (:slug) behave differently
   • Trailing slashes can significantly impact redirect behavior

2. Cloudflare Pages Specifics:

   • The 301 status code is optional in _redirects
   • Single wildcard limitation per rule
   • Cache clearing may be necessary during testing

3. Best Practices:

   • Test redirects with and without trailing slashes
   • Verify redirects in both development and production
   • Use Google Search Console to confirm proper redirection
   • Sometimes, explicit mapping is better than pattern matching

Conclusion

While pattern-based redirects might seem more maintainable, there are cases where explicit URL mapping is the most reliable solution. When dealing with SEO and legacy URLs, the priority should be ensuring consistent and correct behavior, even if it means writing more configuration code.

There's a Japanese proverb that perfectly encapsulates this experience: "Isogaba maware" (急がば回れ) - literally meaning "when in a hurry, take the long way round." In software development, as in life, sometimes the seemingly longer, more methodical approach proves to be the most efficient solution in the end. While pattern matching and wildcards promised a quick fix, the explicit mapping approach, though more time-consuming initially, provided the most reliable and maintainable solution.

Remember: The most elegant solution isn't always the most practical one. In critical infrastructure like URL redirects, reliability should take precedence over conciseness.