Aller au contenu principal

SEO Redirects Implementation

Related Documentation: See ROUTING_GUIDE.md for complete routing architecture

This document explains how the SEO redirect system works in the baldr-template project.

Overview​

The redirect system checks for redirects before loading pages, allowing you to set up 301 (permanent) and 302 (temporary) redirects for SEO purposes.

Integration with Routing:

How It Works​

  1. Route Handling: The catch-all route (app/routes/$.tsx) intercepts all dynamic page requests
  2. Redirect Check: Before loading a page, the loader checks if a redirect exists for the current path
  3. Redirect Execution: If a redirect is found, the user is automatically redirected with the appropriate HTTP status code (301 or 302)
  4. Fallback: If no redirect exists, the page loads normally

Setup​

Environment Configuration​

No special environment configuration is required for redirects. The system works out of the box.

If you need module-specific redirects (advanced usage), you can add your module ID to the .env file:

VITE_MODULE_ID=your_module_id_here

However, for most use cases, the redirect system will work automatically without this configuration.

Backend Configuration​

Ensure your backend has the redirect endpoints available:

  • /redirect/resolve/:path - Resolves a redirect for a given path
  • Returns redirect information including target path and status code

Redirect Features​

Redirect Types​

  • Exact Match: Matches the exact path only
  • Prefix Match: Matches paths that start with the source path
  • Regex Match: Uses regular expressions for complex pattern matching

HTTP Status Codes​

  • 301 (Permanent): Used for permanent redirects, tells search engines to update their index
  • 302 (Temporary): Used for temporary redirects, preserves original URL in search engine index

Additional Features​

  • Case Sensitivity: Optional case-sensitive matching
  • Expiration: Redirects can be set to expire after a specific date
  • Hit Tracking: Backend tracks redirect usage (hit count and last hit date)
  • Validation: Prevents redirect chains and loops

API Reference​

The redirect API is available at app/api/redirect.api.ts and provides the following methods:

// Resolve a redirect for a given path
await redirectApi.resolveRedirect(path);

// With optional module_id for module-specific redirects
await redirectApi.resolveRedirect(path, moduleId);

// Check if a path has a redirect
await redirectApi.checkRedirect(path);

// Get all active redirects (with optional module filter)
await redirectApi.getActive({ module_id: moduleId });

// Get redirect statistics
await redirectApi.getStats(moduleId);

Example Usage​

Creating a Redirect (via Admin Panel)​

  1. Navigate to the SEO module in your admin panel
  2. Create a new redirect:
    • Source Path: /old-page
    • Target Path: /new-page
    • Status Code: 301 (Permanent)
    • Match Type: Exact
    • Active: Yes

Result​

When a user visits https://yoursite.com/old-page, they will be automatically redirected to https://yoursite.com/new-page with a 301 status code.

Error Handling​

If the redirect system encounters an error:

  1. The error is logged to the console
  2. The system continues to attempt loading the page normally
  3. This ensures the site remains functional even if the redirect API is unavailable

Performance Considerations​

  • Redirects are checked on every page load for dynamic routes
  • The redirect check is a single API call before the page data fetch
  • Failed redirect checks fall through quickly to page loading
  • Consider caching redirect rules on the frontend for high-traffic sites

Maintenance​

Monitoring Redirects​

Use the admin panel to:

  • View redirect statistics (hit counts)
  • Identify unused redirects
  • Find expired redirects
  • Validate redirect chains

Best Practices​

  1. Use 301 for permanent URL changes
  2. Use 302 for temporary redirects (A/B testing, maintenance)
  3. Avoid redirect chains (A → B → C)
  4. Set expiration dates for temporary redirects
  5. Regularly audit and clean up old redirects
  6. Test redirects after deployment

Troubleshooting​

Redirect Not Working​

  1. Check if the redirect is active in the admin panel
  2. Verify the source path matches exactly (check case sensitivity)
  3. Check the match type (exact, prefix, or regex)
  4. Check browser console for errors
  5. Verify the backend API is reachable

Redirect Loop​

If you encounter a redirect loop:

  1. Check for circular redirects (A → B → A)
  2. Use the validate chain API endpoint
  3. Disable problematic redirects via admin panel

Module Not Found​

If you're using module-specific features and redirects aren't working:

  1. Verify VITE_MODULE_ID is set in .env (if needed)
  2. Confirm the module ID exists in your backend
  3. Check API connectivity

For most applications, module_id is not required and redirects will work based on path matching alone.

Further Reading​

Last Updated: December 31, 2025