From 3e58e6604e4fb91835ba30f30a1c6293f81178b0 Mon Sep 17 00:00:00 2001
From: Reshmarpillai <reshmarofficial83@gmail.com>
Date: Fri, 27 Mar 2026 02:02:46 +0530
Subject: [PATCH] fix: [WPN-30] Clarify Convex requires 'use node' directive

---
 README.md                  |  5 +++--
 packages/builder/README.md | 10 ++++++++--
 2 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 1e002c6..6c16fea 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,6 @@ Traditional web push libraries like `web-push` rely on Node.js-specific APIs tha
 ```
 ❌ Cloudflare Workers - "crypto.createECDH is not a function"
 ❌ Vercel Edge - "https.request is not available"
-❌ Convex - "Top-level await is not supported"
 ```
 
 ## The Solution
@@ -67,10 +66,12 @@ await fetch(endpoint, { method: "POST", headers, body });
 | Dependencies | **0** | 5+ |
 | Cloudflare Workers | ✅ | [❌](https://github.com/web-push-libs/web-push/issues/718) |
 | Vercel Edge | ✅ | ❌ |
-| Convex | ✅ | ❌ |
+| Convex | ✅* | ❌ |
 | Deno / Bun | ✅ | Limited |
 | TypeScript | Native | @types |
 
+\* Requires `"use node";` directive — [see example](packages/builder#convex)
+
 ## Quick Start
 
 ```bash
diff --git a/packages/builder/README.md b/packages/builder/README.md
index e5f554c..bd7bece 100644
--- a/packages/builder/README.md
+++ b/packages/builder/README.md
@@ -40,10 +40,12 @@ Try PushForge in your browser at **[pushforge.draphy.org](https://pushforge.drap
 | Dependencies | **0** | 5+ (with nested deps) |
 | Cloudflare Workers | Yes | [No](https://github.com/web-push-libs/web-push/issues/718) |
 | Vercel Edge | Yes | No |
-| Convex | Yes | No |
+| Convex | Yes* | No |
 | Deno / Bun | Yes | Limited |
 | TypeScript | First-class | @types package |
 
+\* Convex requires `"use node";` directive. [See example](#convex).
+
 Traditional web push libraries rely on Node.js-specific APIs (`crypto.createECDH`, `https.request`) that don't work in modern edge runtimes. PushForge uses the standard [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API), making it portable across all JavaScript environments.
 
 ## Quick Start
@@ -232,7 +234,11 @@ export default async function handler(request: Request) {
 
 ### Convex
 
+> **Note:** Convex's default runtime doesn't support ECDH operations required by Web Push. Add `"use node";` to use the Node.js runtime.
+
 ```typescript
+"use node";
+
 import { action } from "./_generated/server";
 import { buildPushHTTPRequest } from "@pushforge/builder";
 import { v } from "convex/values";
@@ -327,7 +333,7 @@ self.addEventListener('notificationclick', (event) => {
 | Vercel Edge | Fully supported |
 | Deno | Fully supported |
 | Bun | Fully supported |
-| Convex | Fully supported |
+| Convex | Requires `"use node";` ([example](#convex)) |
 | Modern Browsers | Fully supported |
 
 <details>