Technology Decision Record: Migration from GitHub Pages to Cloudflare Pages

Context

Konnektoren.help is a Single Page Application (SPA) built with Rust and Yew that requires client-side routing. Initially, we hosted the application on GitHub Pages due to its zero-cost hosting solution. However, we encountered significant limitations with routing and SEO optimization.

Problem

1. Routing Issues:

   • GitHub Pages doesn't natively support SPA routing
   • We implemented a 404-based routing solution that redirected all routes to index.html
   • This approach resulted in sending 404 HTTP status codes for valid routes

2. SEO Impact:

   • Search engines interpreted our valid routes as error pages due to the 404 status codes
   • This negatively impacted our search engine rankings
   • Unable to configure proper HTTP response codes on GitHub Pages

Solution: Migration to Cloudflare Pages

Key Benefits

1. Configurable Routing:

   # _redirects file
   /about              /index.html   200
   /achievements       /index.html   200
   /challenge/*       /index.html   200
   # ... other routes
   

2. Custom Headers:

   # _headers file
   /*
     Access-Control-Allow-Origin: *
     X-Frame-Options: SAMEORIGIN
     X-Content-Type-Options: nosniff
   

3. Deployment Workflow:

   • Maintains simple git-based deployment
   • Automatic builds and deployments on push
   • Zero-downtime deployments

4. Cost Consideration:

   • Remains within free tier limits
   • Comparable to GitHub Pages in terms of cost (free)

Consequences

Positive

• Proper HTTP status codes (200) for valid routes
• Improved SEO performance
• Better control over HTTP headers
• Maintained simple deployment process
• Enhanced security headers configuration

Negative

• Additional configuration files to maintain
• Team needs to learn Cloudflare Pages specifics

Conclusion

The migration to Cloudflare Pages solved our critical routing and SEO issues while maintaining a similar deployment workflow. The ability to configure redirects and headers made it the right choice for our SPA needs.

References

• Cloudflare Pages Documentation
• Project Configuration Files:
  • _redirects
  • _headers
  • GitHub Actions workflow

Tokio

For our multiplayer game session management framework, we needed a robust async runtime to handle WebSocket connections and concurrent operations. Tokio emerged as the clear choice for our stack.

The Decision

We chose Tokio as our async runtime because of three key factors:

1. Strong Community & Documentation

   • Extensive, well-maintained documentation
   • Large, active community for support
   • Abundant examples and resources

2. WebSocket Integration

   • Seamless integration with Axum routes
   • Natural WebSocket handling

3. Extensibility

   • Easy to add new async routes
   • Simple integration of different async operations