From b3902d5ca4a1be73740b2cbf1812d258a46e6c14 Mon Sep 17 00:00:00 2001
From: Jamison French <jamison@developmentseed.org>
Date: Mon, 3 Aug 2026 17:40:48 -0500
Subject: [PATCH 1/2] feat: add stac-browser v5.x support

---
 lib/stac-browser/index.ts | 57 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/lib/stac-browser/index.ts b/lib/stac-browser/index.ts
index d7263fcb..dc0979ad 100644
--- a/lib/stac-browser/index.ts
+++ b/lib/stac-browser/index.ts
@@ -58,6 +58,17 @@ export class StacBrowser extends Construct {
 
     }
 
+    /**
+     * Extracts the major version number from a stac-browser git tag, e.g.
+     * "v4.0.1" -> 4, "v5.0.0-rc.2" -> 5, "4.0.1" -> 4.
+     * Returns null if the tag doesn't match a recognizable semver-ish pattern
+     * (e.g. a branch name or commit SHA was passed instead of a version tag).
+     */
+    private static parseMajorVersion(tag: string): number | null {
+        const match = tag.match(/^v?(\d+)\./);
+        return match ? parseInt(match[1], 10) : null;
+    }
+
     private buildApp(props: StacBrowserProps, cloneDirectory: string): string {
 
         // Define where to clone and build
@@ -102,11 +113,32 @@ export class StacBrowser extends Construct {
             fs.copyFileSync(props.configFilePath, `${cloneDirectory}/config.js`);
         }
 
-        // Build the app with catalogUrl
-        console.log(`Building app with catalogUrl=${props.stacCatalogUrl} into ${cloneDirectory}`)
-        execSync(`npm run build -- --catalogUrl=${props.stacCatalogUrl}`, { cwd: cloneDirectory });
+        // Build the app with catalogUrl.
+        // See: https://github.com/radiantearth/stac-browser/discussions/751
+        const majorVersion = StacBrowser.parseMajorVersion(props.githubRepoTag);
+
+        console.log(`Building app with catalogUrl=${props.stacCatalogUrl} into ${cloneDirectory} (detected major version: ${majorVersion ?? 'unknown'})`)
+
+        if (majorVersion !== null && majorVersion <= 3) {
+            // v3.x: CLI flag passthrough
+            const args = [`--catalogUrl="${props.stacCatalogUrl}"`];
+            if (props.pathPrefix) {
+                args.push(`--pathPrefix="${props.pathPrefix}"`);
+            }
+            execSync(`npm run build -- ${args.join(' ')}`, { cwd: cloneDirectory });
+        } else {
+            // v4.x and v5.x (and anything newer, by default assumption): SB_* env vars.
+            execSync('npm run build', {
+                cwd: cloneDirectory,
+                env: {
+                    ...process.env,
+                    SB_catalogUrl: props.stacCatalogUrl,
+                    ...(props.pathPrefix ? { SB_pathPrefix: props.pathPrefix } : {}),
+                },
+            });
+        }
 
-        return './stac-browser/dist'
+        return `${cloneDirectory}/dist`
 
     }
 
@@ -126,20 +158,37 @@ export interface StacBrowserProps {
 
     /**
      * STAC catalog URL. Overrides the catalog URL in the stac-browser configuration.
+     * Backwards compatibility for version prior to v5.0.0.
      */
     readonly stacCatalogUrl: string;
 
     /**
      * Path to config file for the STAC browser. If not provided, default configuration in the STAC browser
      * repository is used.
+     *
+     * Note: config.js option names have changed across major versions (particularly
+     * into v5, which removed/renamed several options). Make sure the config file you
+     * provide matches the schema of the `githubRepoTag` version you're building.
      */
     readonly configFilePath?: string;
 
     /**
      * Tag of the radiant earth stac-browser repo to use to build the app.
+     * Supports v3.x, v4.x, and v5.x tags — the build invocation is automatically
+     * adjusted to match the config mechanism supported by that version.
      */
     readonly githubRepoTag: string;
 
+    /**
+     * Sub-path the app will be hosted under (e.g. "/stac-browser"), if not deployed at
+     * the root of the domain.
+     *
+     * Passed as a `--pathPrefix` CLI flag for v3.x, or as the `SB_pathPrefix`
+     * environment variable for v4.x/v5.x.
+     *
+     * @default - No path prefix. The app is built assuming it is served from the domain root.
+     */
+    readonly pathPrefix?: string;
 
     /**
      * The ARN of the cloudfront distribution that will be added to the bucket policy with read access.

From 83d8e1a574a1a1b93412846b8ec4566887fd4068 Mon Sep 17 00:00:00 2001
From: Jamison French <jamison@developmentseed.org>
Date: Tue, 4 Aug 2026 12:07:13 -0500
Subject: [PATCH 2/2] chore: simplify StacBrowserProps docs

---
 lib/stac-browser/index.ts | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/lib/stac-browser/index.ts b/lib/stac-browser/index.ts
index dc0979ad..a8310e5f 100644
--- a/lib/stac-browser/index.ts
+++ b/lib/stac-browser/index.ts
@@ -158,7 +158,6 @@ export interface StacBrowserProps {
 
     /**
      * STAC catalog URL. Overrides the catalog URL in the stac-browser configuration.
-     * Backwards compatibility for version prior to v5.0.0.
      */
     readonly stacCatalogUrl: string;
 
@@ -174,8 +173,6 @@ export interface StacBrowserProps {
 
     /**
      * Tag of the radiant earth stac-browser repo to use to build the app.
-     * Supports v3.x, v4.x, and v5.x tags — the build invocation is automatically
-     * adjusted to match the config mechanism supported by that version.
      */
     readonly githubRepoTag: string;
 
@@ -183,8 +180,8 @@ export interface StacBrowserProps {
      * Sub-path the app will be hosted under (e.g. "/stac-browser"), if not deployed at
      * the root of the domain.
      *
-     * Passed as a `--pathPrefix` CLI flag for v3.x, or as the `SB_pathPrefix`
-     * environment variable for v4.x/v5.x.
+     * Passed as a `--pathPrefix` CLI flag for <=v3.x, or as the `SB_pathPrefix`
+     * environment variable for >=v4.x.
      *
      * @default - No path prefix. The app is built assuming it is served from the domain root.
      */