feat (ui/react): add resume flag to useChat (vercel#6770)

## Background

Resuming streams on load currently requires `useEffect` and
`experimental_resume`. The DX can be simplified by offering a `resume`
flag on `useChat` that does the same.

## Summary

Add `resume` flag to `useChat` (React).

Author: lgrammel

.changeset/strong-windows-wave.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/react': patch
+---
+
+feat (ui/react): add resume flag to useChat

examples/next-openai/app/use-chat-resume/chat.tsx

@@ -3,7 +3,6 @@
 import { useChat } from '@ai-sdk/react';
 import { DefaultChatTransport, type UIMessage } from 'ai';
 import Link from 'next/link';
-import { useEffect } from 'react';
 import ChatInput from '@component/chat-input';
 
 export function Chat({
@@ -15,31 +14,16 @@ export function Chat({
   autoResume: boolean;
   initialMessages: UIMessage[];
 }) {
-  const {
-    error,
-    status,
-    sendMessage,
-    messages,
-    reload,
-    stop,
-    experimental_resume,
-  } = useChat({
+  const { error, status, sendMessage, messages, reload, stop } = useChat({
     id,
     messages: initialMessages,
     transport: new DefaultChatTransport({ api: '/api/use-chat-resume' }),
     onError: error => {
       console.error('Error streaming text:', error);
     },
+    resume: autoResume,
   });
 
-  useEffect(() => {
-    if (autoResume) {
-      experimental_resume();
-    }
-    // We want to disable the exhaustive deps rule here because we only want to run this effect once
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
   return (
     <div className="flex flex-col w-full max-w-md gap-8 py-24 mx-auto stretch">
       <Link href={`/use-chat-resume/${id}`} target="_noblank">

packages/react/src/use-chat.ts

@@ -4,7 +4,7 @@ import {
   type CreateUIMessage,
   type UIMessage,
 } from 'ai';
-import { useCallback, useRef, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react';
 import { Chat } from './chat.react';
 
 export type { CreateUIMessage, UIMessage };
@@ -45,10 +45,16 @@ Custom throttle wait in ms for the chat messages and data updates.
 Default is undefined, which disables throttling.
    */
   experimental_throttle?: number;
+
+  /**
+   * Whether to resume an ongoing chat generation stream.
+   */
+  resume?: boolean;
 };
 
 export function useChat<UI_MESSAGE extends UIMessage = UIMessage>({
   experimental_throttle: throttleWaitMs,
+  resume = false,
   ...options
 }: UseChatOptions<UI_MESSAGE> = {}): UseChatHelpers<UI_MESSAGE> {
   const chatRef = useRef('chat' in options ? options.chat : new Chat(options));
@@ -87,9 +93,15 @@ export function useChat<UI_MESSAGE extends UIMessage = UIMessage>({
 
       chatRef.current.messages = messagesParam;
     },
-    [messages],
+    [messages, chatRef],
   );
 
+  useEffect(() => {
+    if (resume) {
+      chatRef.current.experimental_resume();
+    }
+  }, [resume, chatRef]);
+
   return {
     id: chatRef.current.id,
     messages,

packages/react/src/use-chat.ui.test.tsx

@@ -1994,7 +1994,7 @@ describe('resume ongoing stream and return assistant message', () => {
 
   setupTestComponent(
     () => {
-      const { messages, status, experimental_resume } = useChat({
+      const { messages, status } = useChat({
         id: '123',
         messages: [
           {
@@ -2004,15 +2004,9 @@ describe('resume ongoing stream and return assistant message', () => {
           },
         ],
         generateId: mockId(),
+        resume: true,
       });
 
-      useEffect(() => {
-        experimental_resume();
-
-        // We want to disable the exhaustive deps rule here because we only want to run this effect once
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-      }, []);
-
       return (
         <div>
           {messages.map((m, idx) => (