Skip to main content
Skip table of contents

Page-level cross-domain redirect for a subdomain that loads proxy-rewrite JS

Last Updated: October 22, 2024

This document helps you to better understand redirecting a singleSubdomain page to VA.gov. This is a page-level cross-domain redirect using the proxy-rewrite JavaScript (JS) app. For more information about redirects, return to the Redirect Implementation Strategy page.

The Sitewide Content, Accessibility & 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.

This is a client-side redirect

Subdomain to VA.gov redirects are client-side redirects. A client-side redirect uses JavaScript (JS). This primarily applies to TeamSite pages that use the injected header and footer, and therefore load the proxy-rewrite JS app. During a client-side redirect, the proxy-rewrite JS app checks for any documented redirects. If a redirect exists, it sends the user to the page’s new destination.

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.

Information Table: Subdomainto VA.gov Redirects

Below is a table that outlines the details of a Subdomainto VA.gov redirect.

Subdomain to VA.gov : Page-level cross-domain redirect for a subdomain that loads proxy-rewrite JS

When to use this redirect:

When a single page within a TeamSite should redirect to VA.gov , and that TeamSite loads proxy-rewrite JS.

Real world example:

The National Cemetery Association TeamSite (www.cem.va.gov) uses the injected header and footer. An example page-level redirect from TeamSite to the modernized VA.gov site:
    domain: "www.cem.va.gov",
    src: /cem/burial_benefits/eligible.asp
    dest: /burials-memorials/eligibility/

How it works:

  1. A browser requests subdomain.va.gov/page

  2. The page at subdomain.va.gov is returned to the user's browser.

  3. The page begins loading, including downloading images, and JavaScript files.

  4. Proxy-rewrite JavaScript code for rendering the modernized header/footer is loaded into the user's browser.

  5. Proxy-rewrite JS code begins executing -

    • If there is a client-side redirect defined in crossDomainRedirects.json, the redirect will execute.

Consider if the redirect should be a catchAll. Example of catchAll code here.

Code location:

https://github.com/department-of-veterans-affairs/vets-website/blob/main/src/applications/proxy-rewrite/redirects/crossDomainRedirects.json#L3C1-L5C46 Any Platform or VFS engineer with repo access may modify.

Additional Info:

You can verify if a site loads proxy-rewrite by checking the proxy-rewrite-whitelist.json.

Typically these sites will display the injected modernized header/footer, but in some cases, sites may load the proxy-rewrite JS but not yet display the injected header. proxy-rewrite-whitelist.json is the source of truth.

Team Responsibilities:

CAIA must sign off on request.

Special Note

Do not archive redirected TeamSite pages. Instead, product team should implement the client side redirect, with additional ask of VA stakeholder to:

  1. ✅ Replace their page content with a 'redirect' message and

  2. ✅ Update their print materials and nav links with the new URL

Additional Resources


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.