From eb20e520a36bf889bba49bdc628f94490177a33c Mon Sep 17 00:00:00 2001
From: Waleed Latif <walif6@gmail.com>
Date: Sat, 24 Oct 2026 11:47:02 -0700
Subject: [PATCH] improvement(docs): build feature-branch docs previews only
 when docs change

Production and staging keep building every affected commit, so a shared-package change that breaks the docs build still fails on staging before main. Other preview branches skip the build unless apps/docs changed since the branch's last successful deployment; a first deployment or a previous SHA outside the shallow clone builds.
---
 apps/docs/scripts/vercel-ignore-build.sh | 28 ++++++++++++++++++++++++
 apps/docs/vercel.json                    |  4 ++++
 2 files changed, 32 insertions(+)
 create mode 100755 apps/docs/scripts/vercel-ignore-build.sh
 create mode 100644 apps/docs/vercel.json

diff --git a/apps/docs/scripts/vercel-ignore-build.sh b/apps/docs/scripts/vercel-ignore-build.sh
new file mode 100755
index 00000000000..321715f109b
--- /dev/null
+++ b/apps/docs/scripts/vercel-ignore-build.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Vercel's Ignored Build Step for the docs project (`ignoreCommand` in vercel.json), run from
+# apps/docs before install. Exit 0 skips the build; exit 1 builds.
+#
+# Vercel's "skip unaffected projects" already drops commits that touch neither docs nor a
+# workspace package it depends on. Of the rest, production and the staging integration branch
+# always build, so a shared-package change that breaks the docs build still fails on staging
+# before it reaches main. Any other preview branch builds only when it changes docs itself.
+#
+# Anything this script cannot decide builds: a branch's first deployment (no previous SHA) and a
+# previous deployment outside the shallow clone.
+set -uo pipefail
+
+if [[ "${VERCEL_ENV:-}" == production || "${VERCEL_GIT_COMMIT_REF:-}" == staging ]]; then
+  exit 1
+fi
+
+previous=${VERCEL_GIT_PREVIOUS_SHA:-}
+if [[ -z "$previous" ]] || ! git cat-file -e "${previous}^{commit}" 2> /dev/null; then
+  echo "No previous deployment in this clone; building."
+  exit 1
+fi
+
+if git diff --quiet "$previous" HEAD -- .; then
+  echo "No docs changes since ${previous}; skipping this preview."
+  exit 0
+fi
+exit 1
diff --git a/apps/docs/vercel.json b/apps/docs/vercel.json
new file mode 100644
index 00000000000..63ab788af4b
--- /dev/null
+++ b/apps/docs/vercel.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "ignoreCommand": "bash scripts/vercel-ignore-build.sh"
+}