Developer docs
Developer docs
Breadcrumbs

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://va.ghe.com/software/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

Help and feedback