feat: add GraphQL subscriptions support via WebSocket (#65)

* feat: add GraphQL subscriptions support via WebSocket

Implements GraphQL subscriptions for v2 using the graphql-ws library with crossws adapter.

Features:
- WebSocket transport with graphql-ws protocol (graphql-transport-ws)
- Support for both GraphQL Yoga and Apollo Server frameworks
- Built-in PubSub utility (createPubSub) for simple pub/sub patterns
- crossws 0.4 compatibility via custom upgrade hook for protocol negotiation
- Automatic WebSocket feature enablement when subscriptions configured

Implementation:
- Uses graphql-ws/use/crossws makeHooks() for protocol handling
- Adds upgrade hook wrapper for Sec-WebSocket-Protocol header (crossws 0.4+)
- Includes playground example with chat subscription demo

Configuration:
```typescript
graphql({
  framework: 'graphql-yoga',
  subscriptions: {
    enabled: true,
    websocket: { enabled: true },
  },
})
```

Usage:
```typescript
import { createPubSub, defineSubscription } from 'nitro-graphql/define'

const pubsub = createPubSub<{ MESSAGE: Message }>()

export const chatSubscription = defineSubscription({
  messageAdded: {
    subscribe: () => pubsub.subscribe('MESSAGE'),
    resolve: (payload) => payload,
  },
})
```

Peer dependency: graphql-ws (required for subscriptions)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: lint

* feat: add examples

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: productdevbook

examples/subscriptions/.gitignore

@@ -0,0 +1,11 @@
+node_modules
+.nitro
+.output
+.graphql
+dist
+*.log
+*.lock
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+bun.lock

examples/subscriptions/README.md

@@ -0,0 +1,37 @@
+# GraphQL Subscriptions Example
+
+Real-time chat with GraphQL Subscriptions over WebSocket.
+
+## Setup
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Test
+
+1. Open http://localhost:3000/api/graphql
+2. Subscribe:
+```graphql
+subscription {
+  messageReceived {
+    id
+    text
+    author
+  }
+}
+```
+
+3. In another tab, send a message:
+```graphql
+mutation {
+  sendMessage(text: "Hello!", author: "User") {
+    id
+  }
+}
+```
+
+## WebSocket Endpoint
+
+`ws://localhost:3000/api/graphql/ws`

examples/subscriptions/graphql/chat.resolver.ts

@@ -0,0 +1,57 @@
+import {
+  createPubSub,
+  defineMutation,
+  defineQuery,
+  defineSubscription,
+} from 'nitro-graphql/define'
+
+interface Message {
+  id: string
+  text: string
+  author: string
+  createdAt: string
+}
+
+const pubsub = createPubSub<{
+  MESSAGE: Message
+  ONLINE: number
+}>()
+
+const messages: Message[] = []
+let onlineCount = 1
+
+export const chatQueries = defineQuery({
+  messages: () => messages,
+  onlineCount: () => onlineCount,
+})
+
+export const chatMutations = defineMutation({
+  sendMessage: async (_, { text, author }: { text: string, author: string }) => {
+    const message: Message = {
+      id: crypto.randomUUID(),
+      text,
+      author,
+      createdAt: new Date().toISOString(),
+    }
+    messages.push(message)
+    await pubsub.publish('MESSAGE', message)
+    return message
+  },
+})
+
+export const chatSubscriptions = defineSubscription({
+  messageReceived: {
+    subscribe: () => pubsub.subscribe('MESSAGE'),
+    resolve: (payload: Message) => payload,
+  },
+  onlineCountChanged: {
+    subscribe: () => pubsub.subscribe('ONLINE'),
+    resolve: (payload: number) => payload,
+  },
+})
+
+// Simulate online count changes
+setInterval(() => {
+  onlineCount = Math.floor(Math.random() * 50) + 1
+  pubsub.publish('ONLINE', onlineCount)
+}, 10000)

examples/subscriptions/graphql/schema.graphql

@@ -0,0 +1,20 @@
+type Query {
+  messages: [Message!]!
+  onlineCount: Int!
+}
+
+type Mutation {
+  sendMessage(text: String!, author: String!): Message!
+}
+
+type Subscription {
+  messageReceived: Message!
+  onlineCountChanged: Int!
+}
+
+type Message {
+  id: ID!
+  text: String!
+  author: String!
+  createdAt: String!
+}

examples/subscriptions/nitro.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'nitro'
+import graphql from 'nitro-graphql'
+
+export default defineConfig({
+  serverDir: './',
+  modules: [
+    graphql({
+      framework: 'graphql-yoga',
+      serverDir: './',
+      subscriptions: {
+        enabled: true,
+        websocket: {
+          enabled: true,
+        },
+      },
+    }),
+  ],
+})

examples/subscriptions/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "nitro-graphql-subscriptions-example",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "nitro build",
+    "dev": "nitro dev",
+    "preview": "npx srvx --prod .output/"
+  },
+  "devDependencies": {
+    "graphql": "^16.12.0",
+    "graphql-ws": "^6.0.6",
+    "graphql-yoga": "^5.18.0",
+    "nitro": "^3.0.1-alpha.1",
+    "nitro-graphql": "2.0.0-beta.50",
+    "rolldown": "^1.0.0-beta.58"
+
+  }
+}

examples/subscriptions/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": ["nitro/tsconfig"],
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "paths": {
+      "~/*": ["./*"],
+      "#graphql/server": ["./.graphql/nitro-graphql-server.d.ts"],
+      "#graphql/client": ["./.graphql/nitro-graphql-client.d.ts"]
+    },
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", ".nitro", ".output"]
+}

package.json

@@ -38,6 +38,10 @@
     "#nitro-graphql/debug-info": {
       "types": "./dist/nitro/virtual/stubs.d.mts",
       "import": "./dist/nitro/virtual/stubs.mjs"
+    },
+    "#nitro-graphql/pubsub": {
+      "types": "./dist/nitro/virtual/stubs.d.mts",
+      "import": "./dist/nitro/virtual/stubs.mjs"
     }
   },
   "exports": {
@@ -72,6 +76,10 @@
     "./nuxt": {
       "types": "./dist/nuxt.d.mts",
       "import": "./dist/nuxt.mjs"
+    },
+    "./pubsub": {
+      "types": "./dist/core/pubsub/index.d.mts",
+      "import": "./dist/core/pubsub/index.mjs"
     }
   },
   "module": "./dist/index.mjs",
@@ -105,6 +113,7 @@
     "playground:nitro": "cd playgrounds/nitro && pnpm install && pnpm dev",
     "playground:nuxt": "cd playgrounds/nuxt && pnpm install && pnpm dev",
     "playground:federation": "cd playgrounds/federation && pnpm install && pnpm dev",
+    "playground:subscriptions": "cd playgrounds/subscriptions && pnpm install && pnpm dev",
     "docs:dev": "cd .docs && pnpm install && pnpm update:metadata && pnpm dev",
     "docs:build": "cd .docs && pnpm install && pnpm update:metadata && pnpm build",
     "docs:preview": "cd .docs && pnpm preview",
@@ -120,11 +129,15 @@
   "peerDependencies": {
     "@apollo/server": "^5.0.0",
     "graphql": "^16.12.0",
+    "graphql-ws": "^6.0.6",
     "nitro": "^3.0.1-alpha.0"
   },
   "peerDependenciesMeta": {
     "@apollo/server": {
       "optional": true
+    },
+    "graphql-ws": {
+      "optional": true
     }
   },
   "dependencies": {

playgrounds/subscriptions/nitro.config.ts

@@ -0,0 +1,20 @@
+import graphql from 'nitro-graphql'
+import { defineNitroConfig } from 'nitro/config'
+
+export default defineNitroConfig({
+  serverDir: './',
+  features: {
+    websocket: true,
+  },
+  modules: [
+    graphql({
+      framework: 'graphql-yoga',
+      subscriptions: {
+        enabled: true,
+        websocket: {
+          enabled: true,
+        },
+      },
+    }),
+  ],
+})

playgrounds/subscriptions/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "nitro-graphql-subscriptions-example",
+  "private": true,
+  "scripts": {
+    "dev": "nitro dev",
+    "build": "nitro build",
+    "preview": "node .output/server/index.mjs"
+  },
+  "dependencies": {
+    "graphql-ws": "catalog:",
+    "nitro-graphql": "link:../.."
+  },
+  "devDependencies": {
+    "nitro": "catalog:",
+    "ws": "catalog:"
+  }
+}