refactor: unify deploy base path handling

joyenjoyer · joyenjoyer · commit 25b0fa2c14ea · 2026-05-20T15:24:16.000+02:00
diff --git a/packages/__docs__/src/index.html b/packages/__docs__/src/index.html
@@ -1,20 +1,20 @@
 <!DOCTYPE html>
 <html lang="en" dir="ltr">
   <head>
-    <base href="/" />
-    <!-- GitHub Pages SPA redirect for subdirectory deployments.
-         When serving this page as 404.html, redirect deep links under
-         /pr-preview/pr-N/ or /latest/ back to the subdirectory root with
-         the route encoded as a query parameter. No-op for root paths. -->
+    <base href="<%= PUBLIC_PATH %>" />
+    <!-- When GH Pages serves this as 404.html, redirect the deep link to the
+         deploy base -->
     <script>
       ;(function () {
+        var base = '<%= PUBLIC_PATH %>'
         var l = window.location
-        var m = l.pathname.match(/^(\/pr-preview\/pr-\d+|\/latest)(\/.*)$/)
-        if (m && m[2] !== '/') {
-          l.replace(
-            m[1] + '/?__spa_route=' + encodeURIComponent(m[2] + l.hash)
-          )
-        }
+        if (l.pathname === base) return
+        if (l.pathname + '/' === base) return
+        if (l.pathname.indexOf(base) !== 0) return
+        var rest = l.pathname.slice(base.length)
+        l.replace(
+          base + '?__spa_route=' + encodeURIComponent('/' + rest + l.hash)
+        )
       })()
     </script>
     <meta charset="utf-8" />
diff --git a/packages/__docs__/src/navigationUtils.ts b/packages/__docs__/src/navigationUtils.ts
@@ -22,36 +22,48 @@
  * SOFTWARE.
  */
 
+// Webpack-injected; equals output.publicPath.
+// Examples: '/', '/latest/', '/pr-preview/pr-123/'.
+declare const __webpack_public_path__: string
+
 const MINOR_VERSION_REGEX = /^v\d+_\d+$/
 
 type ParsedUrl = {
-  prPrefix: string
+  basePrefix: string
   minorVersion: string | null
   page: string
   sectionId: string | undefined
 }
 
+/**
+ * Returns '' for a root deploy, '/latest' on instructure.design,
+ * '/pr-preview/pr-<n>' for PR previews. For sub-host deployments it can be
+ * '/<repo>/pr-preview/pr-<n>'.
+ */
+function getDeployBase(): string {
+  if (typeof __webpack_public_path__ === 'string' && __webpack_public_path__) {
+    return __webpack_public_path__.replace(/\/+$/, '')
+  }
+  return ''
+}
+
 function parseCurrentUrl(): ParsedUrl {
   const { pathname, hash } = window.location
-  const cleanPath = pathname.replace(/^\/+|\/+$/g, '')
+
+  const deployBase = getDeployBase()
+  let rest = pathname
+  if (deployBase && rest.startsWith(deployBase)) {
+    rest = rest.slice(deployBase.length)
+  }
+
+  const cleanPath = rest.replace(/^\/+|\/+$/g, '')
   const segments = cleanPath.split('/').filter(Boolean)
 
-  let prPrefix = ''
+  let appPrefix = ''
   let idx = 0
 
-  // Detect PR preview prefix: /pr-preview/pr-123
-  if (
-    segments.length >= 2 &&
-    segments[0] === 'pr-preview' &&
-    segments[1].startsWith('pr-')
-  ) {
-    prPrefix = `/${segments[0]}/${segments[1]}`
-    idx = 2
-  }
-
-  // Detect /latest/ prefix
-  if (idx === 0 && segments[idx] === 'latest') {
-    prPrefix = '/latest'
+  if (segments[idx] === 'latest') {
+    appPrefix = '/latest'
     idx++
   }
 
@@ -71,7 +83,7 @@ function parseCurrentUrl(): ParsedUrl {
     sectionId = decodeURI(hash.replace(/^#+/, ''))
   }
 
-  return { prPrefix, minorVersion, page, sectionId }
+  return { basePrefix: deployBase + appPrefix, minorVersion, page, sectionId }
 }
 
 type BuildUrlOptions = {
@@ -80,13 +92,13 @@ type BuildUrlOptions = {
 }
 
 function buildUrl(targetPage: string, options?: BuildUrlOptions): string {
-  const { prPrefix } = parseCurrentUrl()
+  const parsed = parseCurrentUrl()
   const minorVersion =
     options?.minorVersion !== undefined
       ? options.minorVersion
-      : parseCurrentUrl().minorVersion
+      : parsed.minorVersion
 
-  let url = prPrefix
+  let url = parsed.basePrefix
 
   if (minorVersion) {
     url += `/${minorVersion}`
@@ -123,7 +135,7 @@ function navigateToVersion(version: string | null): void {
  * On PR previews this is e.g. `/pr-preview/pr-2425`, otherwise empty string.
  */
 function getAssetBasePath(): string {
-  return parseCurrentUrl().prPrefix
+  return getDeployBase()
 }
 
 export {
diff --git a/packages/__docs__/webpack.config.mjs b/packages/__docs__/webpack.config.mjs
@@ -32,7 +32,14 @@ const ENV = process.env.NODE_ENV || 'production'
 const DEBUG = process.env.DEBUG || ENV === 'development'
 const GITHUB_PULL_REQUEST_PREVIEW = process.env.GITHUB_PULL_REQUEST_PREVIEW || 'false'
 const PR_NUMBER = process.env.PR_NUMBER
-const PUBLIC_PATH = process.env.PUBLIC_PATH
+// The URL prefix this build is deployed under. Must end with a trailing
+// slash. Fed into output.publicPath (which webpack exposes at runtime as
+// __webpack_public_path__) and into the HTML template's <base href> and
+// 404 SPA-redirect script. Keeping a single source here means a new deploy
+// target only needs to set this one env var.
+const PUBLIC_PATH =
+  process.env.PUBLIC_PATH ||
+  (PR_NUMBER ? `/pr-preview/pr-${PR_NUMBER}/` : '/')
 
 const outputPath = resolvePath(import.meta.dirname, '__build__')
 
@@ -51,9 +58,7 @@ const config = merge(baseConfig, {
   output: {
     path: outputPath,
     filename: '[name].js',
-    // Builds deployed to subdirectories on GitHub Pages (e.g. /pr-preview/pr-123/
-    // or /latest/) need a matching publicPath so script tags resolve correctly.
-    publicPath: PUBLIC_PATH || (PR_NUMBER ? `/pr-preview/pr-${PR_NUMBER}/` : '/'),
+    publicPath: PUBLIC_PATH,
   },
   devServer: {
     static: {
@@ -69,6 +74,7 @@ const config = merge(baseConfig, {
     new HtmlWebpackPlugin({
       template: './src/index.html',
       chunks: ['main'],
+      templateParameters: { PUBLIC_PATH },
     }),
     new webpack.DefinePlugin({
       'process.env.GITHUB_PULL_REQUEST_PREVIEW': JSON.stringify(GITHUB_PULL_REQUEST_PREVIEW),
