Add support for runtime assets base path variable

[HenriqueLimas]

Summary

This proposal outlines a new feature for the react-router framework mode vite plugin: an assetsBasePathVariable configuration option. This option would allow developers to specify a global variable name that the build manifest will use as a prefix for asset paths. This enables the base path for assets to be determined dynamically at runtime, addressing advanced use cases.

Background and Motivation

Currently, the base path for public assets is statically configured via the base option in the Vite configuration. While sufficient for many applications, this static approach creates challenges in environments where asset paths must be determined dynamically.

For instance, an application might use different CDN domains for staging and production environments.

The current workaround involves post-processing the server build output (virtual:react-router/server-build or output server file) to manually rewrite the asset manifest before it's passed to createRequestHandler. This solution has significant disadvantages and requires developers to interact directly with internal build manifest structures. Using the UNSAFE_AssetsManifest type underscores that this is not a stable public API and is subject to breaking changes in future react-router updates.

A dedicated, stable API for this purpose would improve the developer experience and accommodate more use cases.

Proposed Solution

Add a new option, assetsBasePathVariable, to the react-router plugin configuration. This option will accept a string that corresponds to the name of a global variable where the base path should be built from.

The plugin can leverage Vite's experimental.renderBuiltinUrl API to build this variable to all asset URLs in the generated manifest. At runtime, the developer will be responsible for defining this variable on the globalThis object with the desired base path before the server handles incoming requests.

This approach provides a clean and officially supported mechanism for dynamic asset path resolution, eliminating the need for fragile post-build manipulations.

A similar approach is being used by the Marko Vite plugin where a basePathVar configuration can be passed.

Implementation Example

1. Plugin Configuration (react-router.config.ts)
   Specify the desired variable name in the plugin configuration.

   // react-router.config.ts
   export default {
     assetsBasePathVariable: "ASSETS_BASE_PATH"
   };

2. Runtime Definition (entry.server.ts)
   In the server entry file, set the value of the global variable before the request handler is executed. The value can be sourced dynamically from environment variables, a configuration service, or other means.

   // entry.server.ts
   import { getCdnPath } from "./services/cdn";
   
   // Dynamically set the global variable before request handling.
   globalThis.ASSETS_BASE_PATH = getCdnPath();
   
   export default function handleRequest(/*...*/) {
     // ... request handling logic that uses the manifest
   }