feat: add GraphQL subscriptions support via WebSocket

[productdevbook]

Summary

• Implements GraphQL subscriptions for v2 using graphql-ws library with crossws adapter
• Adds WebSocket transport with graphql-transport-ws protocol
• Includes built-in PubSub utility for simple pub/sub patterns
• Supports both GraphQL Yoga and Apollo Server frameworks

Changes

New Files

• src/core/pubsub/index.ts - Built-in PubSub implementation
• src/nitro/routes/graphql-yoga-ws.ts - Yoga WebSocket handler
• src/nitro/routes/apollo-server-ws.ts - Apollo WebSocket handler
• playgrounds/subscriptions/ - Example chat subscription demo

Modified

• Configuration types for subscriptions
• Route registration for WebSocket endpoints
• Rollup externals for graphql dependency

Usage

// nitro.config.ts
graphql({
  framework: 'graphql-yoga',
  subscriptions: {
    enabled: true,
    websocket: { enabled: true },
  },
})

// resolver
import { createPubSub, defineSubscription } from 'nitro-graphql/define'

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

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

// In mutation
pubsub.publish('MESSAGE', newMessage)

Test plan

• Node.js WebSocket client works
• Protocol negotiation (graphql-transport-ws) works
• GraphQL Yoga framework tested
• Apollo Server framework tested
• PubSub publish/subscribe works
• Browser WebSocket client (pending graphql-ws crossws 0.4 support)

Related Issues

• feat: Add crossws 0.4 support enisdenjo/graphql-ws#663 (crossws 0.4 support)
• feat: allow configuring handleProtocols or change default behavior h3js/crossws#176 (handleProtocols default)
• feat: expose WebSocket serverOptions for crossws adapter nitrojs/nitro#3925 (serverOptions exposure)

🤖 Generated with Claude Code

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	62.68%	850 / 1356
🔵	Statements	62.81%	870 / 1385
🔵	Functions	65.94%	153 / 232
🔵	Branches	51.26%	508 / 991

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/define.ts	100%	100%	100%	100%
src/core/schema/builder.ts	63.63%	56.25%	60%	63.33%	87-92, 132-153
src/nitro/setup.ts	69.56%	42%	81.25%	69.56%	124, 154-157, 166-174, 179, 196-198, 205, 255-268, 284, 307, 318-321
src/nitro/setup/rollup-integration.ts	4.65%	0%	12.5%	5%	23-115, 124-155
src/nitro/setup/routes.ts	78.94%	54.54%	100%	78.94%	32-36, 52-56
src/nitro/setup/scanner.ts	38.7%	24.32%	55.55%	39.34%	95-106, 129-142, 150, 163-204

Generated in workflow #304 for commit faececd by the Vitest Coverage Report Action