How apteryxxyz/next-ws works
Project type and purpose
• Next WS is a Node.js CLI tool and library that “patches” a Next.js app (app-directory only) to add native WebSocket support.
File structure
• Top-level:
• src/cli.ts + src/commands/** → CLI entrypoint and commands (patch, verify)
• src/patches/** → Code that applies/unapplies source edits to Next.js internals
• src/server/** → Runtime server logic: hooks into Next.js’ createServer, sets up ws.Server, resolves user API route handlers
• src/client/** → Front-end React context & helpers for connecting to your new WebSocket endpoints
• examples/** → Four sample Next.js apps showing usage (echo server, chat room, base-path, custom server)
• tests/** → Integration tests driving each example via Playwright
• tsup.config.ts, pnpm-workspace.yaml, package.json → build and workspace config
README for additional insights
• Confirms this is a server-based plugin, not for serverless hosts
• Describes installation, usage (exporting SOCKET() in API route files), and point to examples
• Clarifies peer dependency on ws and that it patches Next.js internals
a. Main components
• Developer / CLI Layer:
– next-ws patch CLI (src/cli.ts → commands/patch.ts → patches/index.ts)
– Patcher module that modifies Next.js server code on disk
• Next.js Core (unmodified + patched):
– HTTP(S) server instanced via patched createServer
– App directory API route loader
• next-ws Runtime (src/server):
– setup() invoked inside patched createServer
– Instantiates ws.WebSocketServer, registers HTTP ‘upgrade’ listener
– Scans app/api//ws/ for exported SOCKET handlers
– On WebSocket connection, dispatches to the correct handler
• Client Library (src/client):
– React context and hook to open WS connections to /api/.../ws
• External services
– ws library (WebSocketServer & WebSocket)
– Node.js HTTP/HTTPS server
• WebSocket Clients (browsers, other services)
b. Relationships and interactions
1. Developer runs npm install next-ws ws → prepare script executes next-ws patch → on-disk patch
2. Developer starts Next.js server → patched createServer calls next-ws setup()
3. setup() creates a ws.Server attached to the HTTP server’s ‘upgrade’ event
4. Incoming browser WS handshake → ws.Server accepts upgrade → looks up matching SOCKET handler → invokes it with (client, request, server, context)
5. Front-end React code uses next-ws client context to open WebSocket to the API route → bi-directional messaging
6. Tests and examples drive end-to-end flows via Playwright
c. Architectural patterns and design principles
• Plugin / patch pattern: injecting behavior into an existing system by source transformation
• Adapter pattern: adapting Node.js HTTP server to WebSocket-aware server
• Modular CLI commands (single-responsibility for patch and verify)
• Convention-over-configuration: auto-discovering SOCKET exports under app/api/**/ws
d. Key technologies and libraries
• Node.js + TypeScript
• Next.js (app directory)
• ws (WebSocket library)
• pnpm / npm / yarn
• tsup (build bundler)
• Playwright (tests)