Understanding onConnect and onDisconnect in GraphQL Subscriptions (WebSocket Lifecycle)

GraphQL subscriptions rely on WebSockets to provide real-time updates.
Two important lifecycle hooks in this process are onConnect and onDisconnect.

This article clearly explains:

  • What onConnect and onDisconnect are
  • Why they are needed
  • When and how they are used
  • Real-world use cases

What Are onConnect and onDisconnect?

In GraphQL subscriptions:

  • onConnect runs when a client establishes a WebSocket connection
  • onDisconnect runs when a client disconnects from the WebSocket

Think of them as entry and exit points of a real-time connection.

What Is onConnect in GraphQL Subscriptions?

Definition

onConnect is a callback function that executes when a client successfully connects to the GraphQL subscription server via WebSocket.

What Happens During onConnect?

When a client connects:

  1. WebSocket connection is opened
  2. Authentication data is sent (e.g., JWT token)
  3. onConnect is triggered on the server
  4. Server validates the client
  5. Context is created for subscriptions

Why onConnect Is Important

onConnect is mainly used for:

  • Authentication & authorization
  • Validating user identity
  • Initializing connection-level data
  • Logging active connections

👉 Without onConnect, subscriptions would be insecure.

Real-World Example of onConnect

Example use cases:

  • Validate JWT token
  • Identify logged-in user
  • Reject unauthorized users
  • Track online users

Simple analogy:

onConnect is like checking an ID card before entering a secure building.

What Is onDisconnect in GraphQL Subscriptions?

Definition

onDisconnect is a callback function that runs when a client disconnects from the WebSocket server.

What Happens During onDisconnect?

When a client disconnects:

  1. User closes browser or app
  2. Network connection drops
  3. WebSocket closes
  4. onDisconnect is triggered
  5. Server cleans up resources

Why onDisconnect Is Important

onDisconnect is used to:

  • Release server resources
  • Stop listening to events
  • Update user online/offline status
  • Clean up memory

👉 Without this, servers may leak resources.

Real-World Example of onDisconnect

Common use cases:

  • Mark user as offline
  • Remove user from active connections list
  • Stop background listeners
  • Log disconnection events

Simple analogy:

onDisconnect is like signing out when leaving the building.

When Are onConnect and onDisconnect Triggered?

EventHook Triggered
WebSocket connection establishedonConnect
WebSocket connection closedonDisconnect
Browser tab closedonDisconnect
Internet lostonDisconnect

Where Do onConnect and onDisconnect Fit in Subscription Lifecycle?

  1. Client opens WebSocket connection
  2. onConnect runs
  3. Client starts subscriptions
  4. Server sends real-time updates
  5. Client disconnects
  6. onDisconnect runs

Common Interview Question

Q: Can onConnect reject a client connection?

Answer:
Yes. If authentication fails inside onConnect, the server can reject the WebSocket connection and prevent subscriptions.

Best Practices

  • Always validate authentication in onConnect
  • Keep onConnect lightweight
  • Clean up all resources in onDisconnect
  • Log connections for debugging
  • Handle unexpected disconnects

When Should You Use onConnect and onDisconnect?

Use them when:

  • Authentication is required for subscriptions
  • You need user presence tracking
  • You want secure real-time communication
  • You need connection-level context

Final Summary

HookPurpose
onConnectAuthenticate & initialize WebSocket connection
onDisconnectCleanup & handle connection termination

onConnect = entry gate
onDisconnect = exit gate

Understanding these two hooks is essential for building secure, scalable real-time GraphQL applications.

Leave a comment