createClient

Creates a Socket.IO-backed URQL client. The connection is not started automatically — use the SocketQLProvider or call connect() manually.

Signature

function createClient(options?: ClientOptions): SocketQLClient

The returned SocketQLClient extends URQL’s Client with additional methods.

Options

Option	Type	Default	Description
path	string	'/ws/'	Socket.IO server path
transports	string[]	['websocket']	Allowed transports
graphqlNamespace	string	'graphql'	Socket.IO namespace to connect to
withCredentials	boolean	—	Send cookies with cross-origin requests
autoConnect	boolean	false	Connect automatically on creation
auth	() => Record<string, any>	—	Return auth data for the connection
onConnect	() => void	—	Called on successful connection
onConnectError	(error: ConnectionError) => void	—	Called when the connection is rejected

Client Methods

Method	Signature	Description
connect	() => void	Initiate the WebSocket connection
disconnect	() => void	Close the WebSocket connection
reconnect	() => void	Disconnect and immediately reconnect (picks up new cookies/auth)
socket	(nsp: string, opts?) => Socket	Create an additional Socket.IO namespace socket via the underlying manager
invalidate	(target: string | DocumentNode | Array) => void	Manually invalidate cached operation results
onConnect	(cb: () => void) => () => void	Subscribe to successful connections. Returns unsubscribe.
onConnectError	(cb: (error: ConnectionError) => void) => () => void	Subscribe to connection errors. Returns unsubscribe.
onReconnect	(cb: () => void) => () => void	Subscribe to successful reconnections. Returns unsubscribe.
onReconnectAttempt	(cb: (attempt: number) => void) => () => void	Subscribe to reconnection attempts. Returns unsubscribe.
onReconnectError	(cb: (error: Error) => void) => () => void	Subscribe to reconnection errors. Returns unsubscribe.
onReconnectFailed	(cb: () => void) => () => void	Called when reconnection fails permanently. Returns unsubscribe.

Note

The onConnect and onConnectError options are convenience shorthands that register listeners at creation time. The client methods allow subscribing and unsubscribing dynamically at any point.

ConnectionError

class ConnectionError extends Error {
  data?: Record<string, any>
}

The data property contains any structured context attached by the server via ConnectionRejectedError’s second argument.

invalidate

// Single query by operation name
client.invalidate('Users')

// Single query by document node
client.invalidate(UsersDocument)

// Multiple queries
client.invalidate(['Users', ProjectsDocument])