disable local caching for hot reload (#6095)

Co-authored-by: Sandeep Dinesh <[email protected]>

Author: thesandlord

packages/commons/docs-loader/src/kv-cache.ts

@@ -16,7 +16,32 @@ export interface KvCache {
 }
 
 /**
- * In-memory cache implementation for local development
+ * No-op cache implementation for local CLI development (fern docs dev)
+ * This ensures hot reload works by never caching any data
+ */
+class NoOpKvCache implements KvCache {
+    async get<T>(_domainKey: string, _key: string, _cacheKeySuffix?: string): Promise<T | null> {
+        // Never return cached data - always fetch fresh
+        return null;
+    }
+
+    async mget(_domainKey: string, _keys: string[], _cacheKeySuffix?: string): Promise<Map<string, unknown>> {
+        // Never return cached data - always fetch fresh
+        return new Map();
+    }
+
+    set(_domainKey: string, _key: string, _value: unknown, _ttl?: number, _cacheKeySuffix?: string): void {
+        // Don't cache anything
+    }
+
+    async clear(_domainKey: string): Promise<void> {
+        // Nothing to clear
+    }
+}
+
+/**
+ * In-memory cache implementation for local development (pnpm docs:dev in monorepo)
+ * When isLocal() is true (fern docs dev CLI), all operations are no-ops to enable hot reload
  */
 class InMemoryKvCache implements KvCache {
     private cache = new Map<string, { value: unknown; expiration?: number }>();
@@ -403,8 +428,20 @@ class UpstashKvCache implements KvCache {
 
 /**
  * Factory function to create the appropriate cache implementation
+ *
+ * - isLocalDev() = true (fern docs dev CLI): No caching at all for hot reload to work
+ * - isDocsDev = true (pnpm docs:dev in monorepo): In-memory cache
+ * - Production: Upstash KV cache
  */
 export function createKvCache(isDocsDev: boolean): KvCache {
+    // For local CLI development (fern docs dev), disable all caching
+    // This ensures hot reload works by fetching fresh data on every request
+    // Use local check instead of imported isLocal() to avoid Next.js env var inlining issues
+    if (isLocal()) {
+        console.debug("[KvCache] Using no-op cache for local CLI development (hot reload enabled)");
+        return new NoOpKvCache();
+    }
+    // For monorepo docs development (pnpm docs:dev), use in-memory cache
     if (isDocsDev) {
         console.debug("[KvCache] Using in-memory cache for docs development");
         return new InMemoryKvCache();

packages/commons/docs-server/src/loadWithUrl.ts

@@ -26,17 +26,38 @@ setGlobalDispatcher(
 );
 
 // In-memory cache for docs dev mode to avoid Next.js 2MB cache limit
-const docsDevCache = new Map<string, FdrAPI.docs.v2.read.LoadDocsForUrlResponse>();
+// Stores both the response and the timestamp for time-based invalidation
+interface CacheEntry {
+    response: FdrAPI.docs.v2.read.LoadDocsForUrlResponse;
+    timestamp: number;
+}
+const docsDevCache = new Map<string, CacheEntry>();
 const pendingRequests = new Map<string, Promise<FdrAPI.docs.v2.read.LoadDocsForUrlResponse>>();
 
+// Cache TTL for local development (2 seconds) to allow hot reload while maintaining some caching
+const LOCAL_CACHE_TTL_MS = 2000;
+
 export const loadWithUrl = async (domain: string): Promise<FdrAPI.docs.v2.read.LoadDocsForUrlResponse> => {
-    // In docs dev mode, use in-memory cache instead of unstable_cache
+    // In docs dev mode (including local CLI), use in-memory cache with time-based invalidation
     if (isDocsDev()) {
-        // Check if we have a cached response
+        const now = Date.now();
         const cached = docsDevCache.get(domain);
+
+        // For local CLI development, use shorter TTL for hot reload
+        const ttl = isLocal() ? LOCAL_CACHE_TTL_MS : Infinity;
+
+        // Check if we have a valid cached response (not expired)
+        if (cached && now - cached.timestamp < ttl) {
+            console.debug(`[DocsDevCache] Cache hit for domain: ${domain} (age: ${now - cached.timestamp}ms)`);
+            return cached.response;
+        }
+
+        // If cache is stale, delete it
         if (cached) {
-            console.debug(`[DocsDevCache] Cache hit for domain: ${domain}`);
-            return cached;
+            console.debug(
+                `[DocsDevCache] Cache expired for domain: ${domain} (age: ${now - cached.timestamp}ms, ttl: ${ttl}ms)`
+            );
+            docsDevCache.delete(domain);
         }
 
         // Check if there's already a pending request for this domain
@@ -51,8 +72,8 @@ export const loadWithUrl = async (domain: string): Promise<FdrAPI.docs.v2.read.L
         const requestPromise = (async () => {
             try {
                 const response = await uncachedLoadWithUrl(domain);
-                // Once resolved, store in cache and remove from pending
-                docsDevCache.set(domain, response);
+                // Once resolved, store in cache with timestamp and remove from pending
+                docsDevCache.set(domain, { response, timestamp: Date.now() });
                 pendingRequests.delete(domain);
                 console.debug(`[DocsDevCache] Cached and cleaned up pending request for domain: ${domain}`);
                 return response;