{"id":20961444,"url":"https://github.com/xd2sketch/react-chat-stream","last_synced_at":"2026-03-13T02:33:38.406Z","repository":{"id":180937756,"uuid":"665428183","full_name":"XD2Sketch/react-chat-stream","owner":"XD2Sketch","description":"⚛️ React Hook to add 🤖 ChatGPT-like word-by-word event streams","archived":false,"fork":false,"pushed_at":"2024-12-01T20:50:07.000Z","size":400,"stargazers_count":64,"open_issues_count":10,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T22:05:26.153Z","etag":null,"topics":["chatgpt","event","event-stream","nextjs","react"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@magicul/react-chat-stream","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XD2Sketch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-12T07:23:28.000Z","updated_at":"2025-02-12T10:08:03.000Z","dependencies_parsed_at":"2023-07-13T12:32:59.622Z","dependency_job_id":"b88594fa-0c35-475e-92e2-57c7f0d00b7f","html_url":"https://github.com/XD2Sketch/react-chat-stream","commit_stats":{"total_commits":34,"total_committers":5,"mean_commits":6.8,"dds":"0.20588235294117652","last_synced_commit":"dcc94c1fe7fd0086e103209473673a34142e14c0"},"previous_names":["xd2sketch/react-chat-stream"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XD2Sketch%2Freact-chat-stream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XD2Sketch%2Freact-chat-stream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XD2Sketch%2Freact-chat-stream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XD2Sketch%2Freact-chat-stream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XD2Sketch","download_url":"https://codeload.github.com/XD2Sketch/react-chat-stream/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280262,"owners_count":20912967,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatgpt","event","event-stream","nextjs","react"],"created_at":"2024-11-19T02:13:38.501Z","updated_at":"2026-03-13T02:33:38.343Z","avatar_url":"https://github.com/XD2Sketch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @magicul/react-chat-stream\n\n![npm bundle size](https://img.shields.io/bundlephobia/min/@magicul/react-chat-stream)\n![npm](https://img.shields.io/npm/dt/@magicul/react-chat-stream)\n![GitHub issues](https://img.shields.io/github/issues/XD2Sketch/react-chat-stream)\n![npm](https://img.shields.io/npm/v/@magicul/react-chat-stream)\n![GitHub Repo stars](https://img.shields.io/github/stars/XD2Sketch/react-chat-stream?style=social)\n\nIntroducing @magicul/react-chat-stream: A React hook designed to simplify integrating\nchat streams returned by your backend. Let messages appear word-by-word similar to ChatGPT.\n\n## What's this package about?\n\nAre you building a ChatGPT-like chat interface? Then most likely you'll want to integrate a chat that has the messages appear word-by-word, similar to ChatGPT. Vercel recently released the [Vercel AI SDK](https://vercel.com/blog/introducing-the-vercel-ai-sdk#streaming-first-ui-helpers) which adds _Streaming First UI Helper_, but what if you want to integrate your own backend? This package solves exactly that pain point. We've abstracted the logic into a React Hook to take care of handling everything for you.\n\n## How does it work?\n![react-chat-stream-demo-long](https://github.com/XD2Sketch/react-chat-stream/assets/5519740/178abe91-e30c-4f33-82cd-64dd66809377)\n\nIf you're backend returns `text/event-stream` then you can use this package. This package does not \"fake\" this response by imitating the word-by-word appearance. It will literally take the responses from your backend as them come in through the stream. The hook provides a `messages` object which will change so you can display it as the result gets delivered.\n\n## Installation\n\nInstall this package with `npm`\n\n```bash\nnpm i @magicul/react-chat-stream\n```\n\nOr with `yarn`\n\n```bash\nyarn add @magicul/react-chat-stream\n```\n\n## Stream chat-like messages from your backend to your React app (similar to ChatGPT).\n\nWith the `useChatStream` hook, you can easily integrate your own API\nto stream chat responses (`text/event-stream`). Responses from your backend will appear\nword-by-word to give it a ChatGPT-like user experience. The following\nexample demonstrates how to use the hook to integrate your own API\nthat streams the results.\n\n_Please note_: Your API has to return `text/event-stream`.\n\n```tsx\nimport React from 'react';\nimport useChatStream from '@magicul/react-chat-stream';\n\nfunction App() {\n  const { messages, input, handleInputChange, handleSubmit } = useChatStream({\n    options: {\n      url: 'https://your-api-url',\n      method: 'POST',\n    },\n    // This means that the user input will be sent as the body of the request with the key 'prompt'.\n    method: {\n      type: 'body',\n      key: 'prompt',\n    },\n  });\n\n  return (\n    \u003cdiv\u003e\n      {messages.map((message, index) =\u003e (\n        \u003cdiv key={message.id}\u003e\n          \u003cp\u003e\n            {message.role}: {message.content}\n          \u003c/p\u003e\n        \u003c/div\u003e\n      ))}\n      \u003cform onSubmit={handleSubmit}\u003e\n        \u003cinput type=\"text\" onChange={handleInputChange} value={input} /\u003e\n        \u003cbutton type=\"submit\"\u003eSend\u003c/button\u003e\n      \u003c/form\u003e\n    \u003c/div\u003e\n  );\n}\n\nexport default App;\n```\n\nThe `useChatStream` hook provides a variable named `messages`. This\n`messages` variable comes from the internal state of the hook. It contains the chat message reply received from\nyour API. Messages are updated in real-time as the stream continues to receive messages. The `messages` variable will change and will get\nappended with new messages received from your backend.\n\n**Important: For this to work, your API must stream back the results\nof the AI model as parts of the string you want to display.**\n\n## Endpoint Requirements\n\nThe API endpoint you provide to the hook must be able to handle the\nfollowing:\n\n- Accept a request with a JSON body or a request with a query string\n  for the prompt.\n- Respond with a `event/text-stream` event stream which contains the\n  responses you would like to display.\n\n## API Reference\n\n### Input:\n\nThe input of the hook is a configuration object with the following\nproperties:\n\n#### options\n\n- url: `string` - the URL of the API endpoint.\n- method: `'GET' | 'POST'` - the HTTP method to use.\n- query: `object (optional)` - the query parameters to send with the\n  request.\n- headers: `object (optional)` - the headers to include in the\n  request.\n- body: `object (optional)` - the body of the request.\n- fakeCharactersPerSecond: `number (optional)` - the number of\n  characters to display per second. If this is unused the hook will display the messages as they come in.\n\n#### method\n\n- type: `'body' | 'query'` - where to include the user's input in the\n  request.\n- key: `string` - the key of the input in the request.\n\n### Output:\n\nThe output of this hook is an object with the following properties:\n\n- messages: `Array\u003cChatMessage\u003e` - an array of chat messages. Each\n  message is an object with an `id` (can be used as a key in the\n  loop), `role` ('bot' or 'user') and `content` (\n  the content of the message).\n- input: `string` - the current user input, you can use this value as\n  the form input value.\n- handleInputChange: `function` - a function to handle the change\n  event of the input field. Pass it to the onChange prop of your input\n  field.\n- handleSubmit: `function` - a function to handle the submit event of\n  the form. Pass it to the onSubmit prop of your form.\n- isLoading: `boolean` - a boolean indicating whether the request is\n  in progress.\n\n## Examples\n\nIf you want to see a working example, check out the [example](./example)\nfolder for an example on how to use this package.\n\n## Important Notes:\n\nFor those utilizing Next.js version 13 or higher as the server-side\nrendering framework with React, it's crucial to incorporate the\nuseChatStream hook within a client component. The need for this is\ndriven by the hook's use of useState, which necessitates its operation\nwithin a client component.\n\nTransforming a regular server component into a client component is a\nstraightforward task. Simply add the following line at the top of your\ncomponent file:\n\n```tsx\n'use client';\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxd2sketch%2Freact-chat-stream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxd2sketch%2Freact-chat-stream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxd2sketch%2Freact-chat-stream/lists"}