Redirect Implementation Strategies

Last Updated: October 22, 2024

Redirects can be a complicated process. This document provides an overview of the most common types of redirects you’ll encounter at VA.gov. On this page, you’ll also find a detailed workflow, guidance on how to select the correct redirect, and how to file requests for approval. Follow the steps in this document – and the related child pages – to preform error-free redirects.

Redirects at VA.gov

At VA.gov, we have two main redirect types:

• Server-side redirects

• Client-side redirects

Let’s take a moment to go over both types. This will provide you with context as we move toward more detailed, complex explanations.

Server-side redirects

A server-side redirect sends a status code to the browser. This status code lets the browser know that the requested page has moved – or is no longer available – and points the browser toward the page’s new URL. Server-side redirects can be temporary or permanent.

Server-side redirects are preferred.

Client-side redirects

A client-side redirect uses JavaScript (JS). During a client-side redirect, JS checks for any documented redirects as the page loads. If a redirect exists, it sends the user to the page’s new destination.

We primarily use this approach for legacy TeamSite pages that are being redirected to modernized pages on VA.gov. If a legacy TeamSite page uses the injected header and footer, it will also include JS from the proxy-rewrite application that can check for and execute redirects, using this method.

Client-side redirects should only be used when absolutely necessary.

Client-side redirects are not ideal, as they require JavaScript to be enabled and running correctly in order for a user to be redirected properly. A client-side redirect also depends on the legacy page staying alive and should, therefore, be considered a temporary solution.

How to choose between a server-side and client-side redirect

Your choice between server-side and client-side redirects depends on where the soon-to-be-redirected page lives. The information in the document that follows will help you decide on the correct redirect.

• For a visual walk through of the decision-making process, reference the Redirect Implementation Workflow.

• To quickly compare the main redirect types, reference the Redirect Types Comparison Table below.

Before you can implement a redirect, however, you must submit the request for approval.

Request for approval

The Sitewide Content, Accessibility, and Information Architecture team (CAIA) reviews all URL redirects before routing them to the appropriate engineer.

Before you attempt a redirect, follow these two important steps:

1. File a redirect request ticket on GitHub.

2. Read the Design System guidance for redirects.

Now it's time to review and compare the specific types of redirects.

Redirect Types

We do not create redirects for any static documents like PDFs. For more on this, head over to the Redirecting Static Documents page.

There are seven main types of redirects. Below you’ll find a quick reference table that outlines the seven major types of redirects and how they differ from each other.

NOTE: To learn more about each individual redirect in the table below, select the title of the redirect to get sent to a page dedicated to explaining that specific redirect.

Redirect Implementation Workflow

To help you better understand the redirect process, you’ll find a workflow diagram below. It will help you comprehend what teams are involved, when they are involved, and why. It will also outline how you arrive at the correct redirect for each redirect request.

Questions

For questions regarding your redirect approval, contact the CAIA team. You can reach them on their Slack channel: #sitewide-content-accessibility-ia.

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.