@blinkdotnew/sdk 0.14.7 → 0.14.8

package/README.md

@@ -958,6 +958,8 @@ blink.analytics.clearAttribution()
 **🎉 Zero-Boilerplate Connection Management!**  
 All connection states, queuing, and reconnection are handled automatically. No more "CONNECTING state" errors!
 
+**⚠️ React Users**: See the [React + Realtime Connections](#react--realtime-connections) section below for proper async cleanup patterns to avoid "Subscription cancelled" errors.
+
 ```typescript
 // 🔥 Real-time Messaging & Presence (NEW!)
 // Perfect for chat apps, live collaboration, multiplayer games, and live updates
@@ -1270,6 +1272,20 @@ All `{{secret_name}}` placeholders are replaced with encrypted values from your
 
 **⚠️ Critical: Avoid Multiple WebSocket Connections**
 
+The most common mistake is using async functions in useEffect that lose the cleanup function:
+
+```typescript
+// ❌ WRONG - Async function loses cleanup (causes "Subscription cancelled" errors)
+useEffect(() => {
+  const initApp = async () => {
+    const channel = blink.realtime.channel('room')
+    await channel.subscribe({ userId: user.id })
+    return () => channel.unsubscribe() // ❌ CLEANUP LOST!
+  }
+  initApp() // Returns Promise, not cleanup function
+}, [])
+```
+
 ```typescript
 // ❌ WRONG - Creates new connection on every user change
 useEffect(() => {
@@ -1280,54 +1296,46 @@ useEffect(() => {
 ```
 
 ```typescript
-// ✅ CORRECT - Single stable connection
-const userRef = useRef(user)
-const [isConnected, setIsConnected] = useState(false)
-
-useEffect(() => { userRef.current = user }, [user])
-
+// ✅ CORRECT - Proper async cleanup handling
 useEffect(() => {
-  if (!user?.id) return
-  
-  const channel = blink.realtime.channel('room')
-  let isMounted = true, isSubscribed = false
+  let channel = null
   
-  const setup = async () => {
-    if (!isMounted) return
-    try {
-      await channel.subscribe({ 
-        userId: userRef.current.id, 
-        metadata: { name: userRef.current.name } 
-      })
-      if (!isMounted) return
-      isSubscribed = true
-      setIsConnected(true)
-      
-      channel.onMessage((msg) => {
-        if (!isMounted) return
-        // handle message
-      })
-    } catch (error) {
-      console.error('Connection failed:', error)
-    }
+  const initApp = async () => {
+    channel = blink.realtime.channel('room')
+    await channel.subscribe({ userId: user.id })
   }
   
-  setup()
+  initApp().catch(console.error)
+  
+  // Cleanup runs when component unmounts
   return () => {
-    isMounted = false
-    setIsConnected(false)
-    if (isSubscribed) channel.unsubscribe()
+    channel?.unsubscribe()
   }
 }, [user.id]) // ✅ Only user.id dependency
+```
 
-// Publish works automatically - no connection checks needed!
-await blink.realtime.publish('room', 'message', data)
+```typescript
+// ✅ ALTERNATIVE - Using state for cleanup
+const [channel, setChannel] = useState(null)
+
+useEffect(() => {
+  const initApp = async () => {
+    const ch = blink.realtime.channel('room')
+    await ch.subscribe({ userId: user.id })
+    setChannel(ch)
+  }
+  initApp().catch(console.error)
+}, [user.id])
+
+useEffect(() => {
+  return () => channel?.unsubscribe()
+}, [channel])
 ```
 
 **Rules:**
-1. **useEffect dependency**: `[user.id]` not `[user]`
-2. **Use useRef**: Store user data to avoid re-connections
-3. **Add isMounted**: Prevent operations on unmounted components
+1. **Never return cleanup from async functions** - useEffect cleanup must be synchronous
+2. **useEffect dependency**: `[user.id]` not `[user]` to avoid reconnections  
+3. **Store channel reference** outside async function for cleanup access
 4. **Zero connection management**: SDK handles all connection states automatically
 
 ### React
@@ -1455,10 +1463,11 @@ function RealtimeChat() {
   const [user] = useState({ id: 'user123', name: 'John Doe' }) // From auth
   
   useEffect(() => {
-    const channel = blink.realtime.channel('chat-room')
+    let channel = null
     
     // Subscribe and listen for messages
     const setupRealtime = async () => {
+      channel = blink.realtime.channel('chat-room')
       await channel.subscribe({
         userId: user.id,
         metadata: { displayName: user.name, avatar: '/avatar.png' }
@@ -1498,11 +1507,11 @@ function RealtimeChat() {
       })))
     }
     
-    setupRealtime()
+    setupRealtime().catch(console.error)
     
     // Cleanup on unmount
     return () => {
-      channel.unsubscribe()
+      channel?.unsubscribe()
     }
   }, [user.id, user.name])
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blinkdotnew/sdk",
-  "version": "0.14.7",
+  "version": "0.14.8",
   "description": "Blink TypeScript SDK for client-side applications - Zero-boilerplate CRUD + auth + AI + analytics + notifications for modern SaaS/AI apps",
   "keywords": [
     "blink",