Skip to content
Beef Docs

Version Update Banner

Version Update Banner

Overview

The version update banner is a notification system that detects when a new version of the application has been deployed and prompts users to refresh their browser to get the latest updates. This ensures users are always running the latest version of the application, especially after critical updates or new features are deployed.

How It Works

Architecture

The system uses a version-based detection mechanism that compares the client-side version with the server-side version:

  1. Version Definition: The server maintains a version identifier (APP_REFRESH_VERSION) in apps/brisket/src/server/api/app-refresh-version.ts
  2. Header Transmission: This version is sent in the x-app-refresh-version response header on all tRPC requests
  3. Client Tracking: The client tracks two versions:
    • Browser Version: The version that was loaded when the page first rendered
    • Server Version: The latest version received from the API

Detection Flow

  1. Initial Load: On the first tRPC request, both browserVersion and serverVersion are set to the same value (establishing a baseline)
  2. Subsequent Requests: On following requests, only serverVersion is updated with the value from the response header
  3. Stale Detection: When browserVersion !== serverVersion, the app is considered “stale” and the banner is displayed
  4. User Action: When the user clicks “Refresh”, the page reloads, loading the new version

How to Trigger the Banner

To trigger the version update banner for users, follow these steps:

Step 1: Update the Version String

Edit the version constant in apps/brisket/src/server/api/app-refresh-version.ts:

export const APP_REFRESH_VERSION = "2025.11.24.1" as const;

Version Format: The version string can be any format you prefer. Common patterns include:

  • Date-based: "2025.11.24.1" (YYYY.MM.DD.revision)
  • Semantic: "1.2.3"
  • Build number: "build-1234"

Important: The version string must be different from the previous version to trigger the banner.

Step 2: Deploy the Changes

  1. Commit the version change
  2. Deploy the new version to your environment (staging/production)
  3. Wait for the deployment to complete

Step 3: Banner Appears

Users with the old version cached in their browser will see the banner on their next tRPC request. The banner appears:

  • At the top of the page on mobile devices
  • At the bottom of the page on desktop
  • With a blue gradient background and a refresh button

This feature was introduced in PR #1832.