From d839b499c8c7ed4e67664c1fca84c827d7521e1d Mon Sep 17 00:00:00 2001
From: Philippe Serhal <philippe.serhal@gmail.com>
Date: Mon, 23 Feb 2026 21:05:06 -0500
Subject: [PATCH 1/3] docs: add contributing section about cache busting in dev

---
 CONTRIBUTING.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9020552d0..db157401e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,6 +31,7 @@ This focus helps guide our project decisions as a community and what we choose t
   - [Setup](#setup)
 - [Development workflow](#development-workflow)
   - [Available commands](#available-commands)
+  - [Clearing caches during development](#clearing-caches-during-development)
   - [Project structure](#project-structure)
   - [Local connector CLI](#local-connector-cli)
   - [Mock connector (for local development)](#mock-connector-for-local-development)
@@ -124,6 +125,20 @@ pnpm test:a11y        # Lighthouse accessibility audits
 pnpm test:perf        # Lighthouse performance audits (CLS)
 ```
 
+### Clearing caches during development
+
+Nitro persists `defineCachedEventHandler` results to disk at `.nuxt/cache/nitro/`. This cache **survives dev server restarts**. If you're iterating on a cached API route and want fresh results, delete the relevant cache file:
+
+```bash
+# Clear all Nitro handler caches
+rm -rf .nuxt/cache/nitro/handlers/
+
+# Clear a specific handler cache (e.g. picks)
+rm -rf .nuxt/cache/nitro/handlers/npmx-picks/
+```
+
+The `.cache/` directory is a separate storage mount used for fetch-cache and atproto data.
+
 ### Project structure
 
 ```

From 36547794024ad6442b6674288e84e8fda30ea0e2 Mon Sep 17 00:00:00 2001
From: James Garbutt <43081j@users.noreply.github.com>
Date: Tue, 24 Feb 2026 11:46:10 +0000
Subject: [PATCH 2/3] chore: change wording to be directory

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index db157401e..f222cff95 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -127,7 +127,7 @@ pnpm test:perf        # Lighthouse performance audits (CLS)
 
 ### Clearing caches during development
 
-Nitro persists `defineCachedEventHandler` results to disk at `.nuxt/cache/nitro/`. This cache **survives dev server restarts**. If you're iterating on a cached API route and want fresh results, delete the relevant cache file:
+Nitro persists `defineCachedEventHandler` results to disk at `.nuxt/cache/nitro/`. This cache **survives dev server restarts**. If you're iterating on a cached API route and want fresh results, delete the relevant cache directory:
 
 ```bash
 # Clear all Nitro handler caches

From 0ec4b7a282b19525921b9f7ab6f0867e0d1c06eb Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Tue, 24 Feb 2026 11:46:42 +0000
Subject: [PATCH 3/3] docs: mention `shouldBypassCache`

---
 CONTRIBUTING.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f222cff95..26cd89c51 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -137,6 +137,20 @@ rm -rf .nuxt/cache/nitro/handlers/
 rm -rf .nuxt/cache/nitro/handlers/npmx-picks/
 ```
 
+Alternatively, you can bypass the cache entirely in development by adding `shouldBypassCache: () => import.meta.dev` to your `defineCachedEventHandler` options:
+
+```ts
+export default defineCachedEventHandler(
+  async event => {
+    // ...
+  },
+  {
+    maxAge: 60 * 5,
+    shouldBypassCache: () => import.meta.dev,
+  },
+)
+```
+
 The `.cache/` directory is a separate storage mount used for fetch-cache and atproto data.
 
 ### Project structure