ci(repo): cache snapi baselines and watch @clerk/ui

Publish the API baseline to a GHA cache on push to main and the release
branches, keyed by commit sha. PR runs restore from that cache with a
prefix-match fallback, and only rebuild the baseline via worktree on a
full miss.

Add @clerk/ui to the watched package set with a tsc-based
build:declarations task matching @clerk/shared's pattern.

Author: jacekradko

.github/workflows/api-changes.yml

@@ -1,6 +1,18 @@
 name: API Changes
 
 on:
+  push:
+    branches:
+      - main
+      - release/v4
+      - release/core-2
+    paths:
+      - 'packages/clerk-js/**'
+      - 'packages/react/**'
+      - 'packages/shared/**'
+      - 'packages/ui/**'
+      - 'snapi.config.json'
+      - '.github/workflows/api-changes.yml'
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
     branches:
@@ -11,6 +23,7 @@ on:
       - 'packages/clerk-js/**'
       - 'packages/react/**'
       - 'packages/shared/**'
+      - 'packages/ui/**'
       - 'snapi.config.json'
       - '.github/workflows/api-changes.yml'
 
@@ -19,11 +32,58 @@ permissions:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  SNAPI_PACKAGE: github:clerk/snapi#8c021a2796b313cdefa945a715df8f02e4f99867
+  SNAPI_FILTERS: >-
+    --filter=@clerk/clerk-js
+    --filter=@clerk/react
+    --filter=@clerk/shared
+    --filter=@clerk/ui
 
 jobs:
+  publish-baseline:
+    if: github.event_name == 'push'
+    name: Publish API Baseline
+    runs-on: 'blacksmith-8vcpu-ubuntu-2204'
+    continue-on-error: true
+    defaults:
+      run:
+        shell: bash
+    timeout-minutes: ${{ vars.TIMEOUT_MINUTES_NORMAL && fromJSON(vars.TIMEOUT_MINUTES_NORMAL) || 10 }}
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+        with:
+          filter: 'blob:none'
+          show-progress: false
+
+      - name: Setup
+        uses: ./.github/actions/init-blacksmith
+        with:
+          cache-enabled: true
+          turbo-signature: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
+          turbo-team: ${{ vars.TURBO_TEAM }}
+          turbo-token: ${{ secrets.TURBO_TOKEN }}
+
+      - name: Build declarations
+        run: pnpm turbo build:declarations $TURBO_ARGS $SNAPI_FILTERS
+
+      - name: Generate API snapshot
+        run: |
+          pnpm dlx --package "$SNAPI_PACKAGE" snapi snapshot \
+            --output "$GITHUB_WORKSPACE/.api-snapshots-baseline"
+
+      - name: Save baseline to cache
+        uses: actions/cache/save@v4
+        with:
+          path: .api-snapshots-baseline
+          key: snapi-baseline-${{ github.sha }}
+
   check-api:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    if: ${{ github.event_name == 'pull_request' && github.event.pull_request.draft == false }}
     name: API Changes
     runs-on: 'blacksmith-8vcpu-ubuntu-2204'
     continue-on-error: true
@@ -32,13 +92,6 @@ jobs:
         shell: bash
     timeout-minutes: ${{ vars.TIMEOUT_MINUTES_NORMAL && fromJSON(vars.TIMEOUT_MINUTES_NORMAL) || 10 }}
 
-    env:
-      SNAPI_PACKAGE: github:clerk/snapi#8c021a2796b313cdefa945a715df8f02e4f99867
-      SNAPI_FILTERS: >-
-        --filter=@clerk/clerk-js
-        --filter=@clerk/react
-        --filter=@clerk/shared
-
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4
@@ -48,34 +101,47 @@ jobs:
           filter: 'blob:none'
           show-progress: false
 
-      - name: Fetch base branch
-        run: git fetch origin "${GITHUB_BASE_REF}:refs/remotes/origin/${GITHUB_BASE_REF}" --depth=100
-
       - name: Setup
-        id: config
         uses: ./.github/actions/init-blacksmith
         with:
           cache-enabled: true
           turbo-signature: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }}
           turbo-team: ${{ vars.TURBO_TEAM }}
           turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+      - name: Restore baseline from cache
+        id: baseline-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: .api-snapshots-baseline
+          key: snapi-baseline-${{ github.event.pull_request.base.sha }}
+          restore-keys: |
+            snapi-baseline-
+
       - name: Build current declarations
         run: pnpm turbo build:declarations $TURBO_ARGS $SNAPI_FILTERS
 
+      - name: Fetch base branch
+        if: steps.baseline-cache.outputs.cache-matched-key == ''
+        run: git fetch origin "${GITHUB_BASE_REF}:refs/remotes/origin/${GITHUB_BASE_REF}" --depth=100
+
       - name: Create baseline worktree
+        if: steps.baseline-cache.outputs.cache-matched-key == ''
         run: |
           mkdir -p .worktrees
           git worktree add .worktrees/snapi-baseline "origin/${GITHUB_BASE_REF}"
           cp snapi.config.json .worktrees/snapi-baseline/snapi.config.json
 
       - name: Install baseline dependencies
+        if: steps.baseline-cache.outputs.cache-matched-key == ''
         run: pnpm --dir .worktrees/snapi-baseline install --frozen-lockfile
 
       - name: Build baseline declarations
+        if: steps.baseline-cache.outputs.cache-matched-key == ''
         run: pnpm --dir .worktrees/snapi-baseline turbo build:declarations $TURBO_ARGS $SNAPI_FILTERS
 
       - name: Generate baseline API snapshots
+        if: steps.baseline-cache.outputs.cache-matched-key == ''
         run: |
           pnpm --dir .worktrees/snapi-baseline dlx --package "$SNAPI_PACKAGE" snapi snapshot \
             --output "$GITHUB_WORKSPACE/.api-snapshots-baseline"

packages/ui/package.json

@@ -71,6 +71,7 @@
   "scripts": {
     "build": "pnpm build:umd && pnpm build:esm && pnpm check:no-rhc && pnpm type-check",
     "build:analyze": "rspack build --config rspack.config.js --env production --env analyze --analyze",
+    "build:declarations": "tsc -p tsconfig.declarations.json",
     "build:esm": "tsdown",
     "build:rsdoctor": "RSDOCTOR=true rspack build --config rspack.config.js --env production",
     "build:umd": "rspack build --config rspack.config.js --env production",

packages/ui/tsconfig.declarations.json

@@ -0,0 +1,21 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "./dist",
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "skipLibCheck": true
+  },
+  "exclude": [
+    "node_modules",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/__tests__/**",
+    "**/__mocks__/**",
+    "**/test/**",
+    "**/tests/**"
+  ]
+}

snapi.config.json

@@ -1,5 +1,5 @@
 {
-  "packages": ["packages/clerk-js", "packages/react", "packages/shared"],
+  "packages": ["packages/clerk-js", "packages/react", "packages/shared", "packages/ui"],
   "snapshotDir": ".api-snapshots",
   "mainBranch": "main",
   "checkVersionBump": true,