{"id":30858585,"url":"https://github.com/ndamulelonemakh/nextjs-react-sse-starter","last_synced_at":"2026-05-09T03:34:56.620Z","repository":{"id":307903859,"uuid":"1031038371","full_name":"ndamulelonemakh/nextjs-react-sse-starter","owner":"ndamulelonemakh","description":"A demonstration of Server-Sent Events (SSE) streaming between a Next.js React frontend and FastAPI Python backend. ","archived":false,"fork":false,"pushed_at":"2025-08-02T21:51:54.000Z","size":113,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T06:39:14.025Z","etag":null,"topics":["eventsource-api","fastapi","nextjs","sse","streaming"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ndamulelonemakh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-08-02T21:47:33.000Z","updated_at":"2025-08-02T21:59:30.000Z","dependencies_parsed_at":"2025-08-02T23:45:27.734Z","dependency_job_id":null,"html_url":"https://github.com/ndamulelonemakh/nextjs-react-sse-starter","commit_stats":null,"previous_names":["ndamulelonemakh/nextjs-react-sse-starter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ndamulelonemakh/nextjs-react-sse-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndamulelonemakh%2Fnextjs-react-sse-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndamulelonemakh%2Fnextjs-react-sse-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndamulelonemakh%2Fnextjs-react-sse-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndamulelonemakh%2Fnextjs-react-sse-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ndamulelonemakh","download_url":"https://codeload.github.com/ndamulelonemakh/nextjs-react-sse-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ndamulelonemakh%2Fnextjs-react-sse-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274046007,"owners_count":25212983,"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","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["eventsource-api","fastapi","nextjs","sse","streaming"],"created_at":"2025-09-07T14:14:33.771Z","updated_at":"2026-05-09T03:34:51.580Z","avatar_url":"https://github.com/ndamulelonemakh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NextJS React SSE FastAPI Demo\n\nA demonstration of Server-Sent Events (SSE) streaming between a Next.js React frontend and FastAPI Python backend. This repo shows how to implement, customize, and optimize real-time streaming for AI.\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fndamulelonemakh%2Fnextjs-react-sse-starter\u0026env=OPENAI_API_KEY\u0026envDescription=API%20keys%20needed%20for%20application\u0026project-name=nextjs-react-sse-starter\u0026repository-name=nextjs-react-sse-starter)\n\n## 🚀 Key Features\n\n- **Raw SSE Protocol Exploration**: See exactly how SSE works under the hood\n- **Custom Streaming Protocols**: Create your own message formats and event types\n- **Function Calling**: Demonstrate tool/function calling during streaming\n- **Interactive Debug Console**: Visualize and inspect every streaming event\n\n## ✨ Why Server-Sent Events?\n\nServer-Sent Events (SSE) provide a simple, efficient way for servers to push data to clients over a single HTTP connection. Unlike WebSockets, SSE:\n\n- Only flows in one direction (server → client)\n- Uses standard HTTP, not a separate protocol\n- Has built-in reconnection handling\n- Works through most firewalls and proxies\n- Has native browser support via the EventSource API\n\nThis makes SSE ideal for real-time updates like notifications, data feeds, and—as shown in this demo—streaming AI responses.\n\n## 🛠️ Project Structure\n\n```\n/\n├── api/                  # FastAPI backend\n│   ├── index.py          # Main API with streaming endpoints\n│   └── utils/            # Helper functions and tools\n├── app/                  # Next.js pages\n│   ├── debug/            # Raw stream debug console\n│   └── page.tsx          # Custom protocol demo\n├── components/           # React components\n```\n\n## 🔮 Streaming Protocol Examples\n\nThis demo showcases multiple approaches to streaming protocols:\n\n### 1. Vercel AI SDK Protocol\n\nThe original Vercel AI SDK protocol uses numeric and alphabetic prefixes:\n\n```\n0:{\"Hello\"}             # Content token\n9:{\"toolCallId\":\"123\"}  # Function call\na:{\"result\":\"data\"}     # Function result\ne:{\"finishReason\":\"stop\"} # End of stream\n```\n\n### 2. Custom Semantic Protocol\n\nA more readable custom protocol with meaningful prefixes:\n\n```\nTEXT: \"Hello there\"              # Content token\nFUNC: {\"name\":\"get_weather\"}     # Function call\nRESP: {\"result\":{\"temp\":72}}     # Function result\nMETA: {\"tokens\":45}              # Stream metadata\nDEBUG: {\"event\":\"stream_start\"}  # Debug information\n```\n\n## 🔄 SSE Limitations \u0026 Best Practices\n\n- **Connection Limits**: Browsers typically limit to 6 connections per domain in HTTP/1.1\n- **Message Size**: No official size limit, but best to send many small messages\n- **Timeouts**: Use heartbeat messages to keep connections alive\n- **Binary Data**: SSE is text-only (UTF-8); binary data must be encoded\n- **Reconnection**: Implement proper reconnection strategies for reliability\n\n## 📚 Advanced Features\n\n### Microsoft SSE Client Library\n\nFor production applications, consider using [microsoft/fetch-event-source](https://github.com/microsoft/fetch-event-source), which provides:\n\n```javascript\n// Usage example:\nimport { fetchEventSource } from \"@microsoft/fetch-event-source\";\n\nfetchEventSource(\"/api/stream\", {\n  onmessage(event) {\n    console.log(event.data);\n  },\n  onerror(err) {},\n  onclose() {},\n  openWhenHidden: true,\n  // Many more options!\n});\n```\n\n## 🚀 Getting Started\n\nTo run the example locally you need to:\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   pnpm install\n   pip install -r requirements.txt\n   ```\n3. Create `.env.local` with your OpenAI API key:\n   ```\n   OPENAI_API_KEY=your_key_here\n   ```\n4. Run the development server:\n   ```bash\n   pnpm run dev\n   ```\n5. Open [http://localhost:3000](http://localhost:3000)\n\n## 📊 Demo Pages\n\n- **/**: Custom streaming protocol demo (main page)\n- **/debug**: Raw SSE protocol visualization\n\n## � Acknowledgments\n\nThis project was inspired by the work from the Vercel team on [ai-sdk-preview-python-streaming](https://github.com/vercel-labs/ai-sdk-preview-python-streaming). We've built upon their foundation to create an updated version of NextJS and more explicit handling of events to demonstate a `behind-the-scenes` look at how SSE works.\n\n## �📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndamulelonemakh%2Fnextjs-react-sse-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fndamulelonemakh%2Fnextjs-react-sse-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fndamulelonemakh%2Fnextjs-react-sse-starter/lists"}