SpringbootHow-ToBeginner · 4 min read

How to Use SockJS with Spring Boot for WebSocket Fallback

To use SockJS with Spring Boot, enable WebSocket support by implementing WebSocketMessageBrokerConfigurer and register SockJS in the registerStompEndpoints method with withSockJS(). This allows fallback options for browsers that do not support native WebSockets.

📐

Syntax

In Spring Boot, you configure SockJS by overriding the registerStompEndpoints method in a class that implements WebSocketMessageBrokerConfigurer. You add an endpoint with registry.addEndpoint("/your-endpoint") and enable SockJS fallback with withSockJS().

addEndpoint: Defines the WebSocket endpoint URL.
withSockJS(): Enables SockJS fallback options for clients without WebSocket support.

java

import org.springframework.context.annotation.Configuration;
import org.springframework.messaging.simp.config.MessageBrokerRegistry;
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws-endpoint").withSockJS();
    }

    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic");
        config.setApplicationDestinationPrefixes("/app");
    }
}

💻

Example

This example shows a complete Spring Boot WebSocket configuration using SockJS. It defines a STOMP endpoint at /ws-endpoint with SockJS fallback enabled. The message broker is configured to handle messages prefixed with /app and broadcast to clients subscribed to /topic.

java

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Configuration;
import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.messaging.handler.annotation.SendTo;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;
import org.springframework.messaging.simp.config.MessageBrokerRegistry;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@Configuration
@EnableWebSocketMessageBroker
class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws-endpoint").withSockJS();
    }

    @Override
    public void configureMessageBroker(MessageBrokerRegistry config) {
        config.enableSimpleBroker("/topic");
        config.setApplicationDestinationPrefixes("/app");
    }
}

@Controller
class GreetingController {
    @MessageMapping("/hello")
    @SendTo("/topic/greetings")
    public String greeting(String message) throws Exception {
        Thread.sleep(1000); // simulated delay
        return "Hello, " + message + "!";
    }
}

@Controller
class HomeController {
    @GetMapping("/")
    public String home() {
        return "index"; // returns a view named index.html
    }
}

Output

Spring Boot app starts with WebSocket endpoint at /ws-endpoint supporting SockJS fallback; clients can send messages to /app/hello and receive broadcasts on /topic/greetings.

⚠️

Common Pitfalls

Common mistakes when using SockJS with Spring Boot include:

Not calling withSockJS() on the endpoint, which disables fallback support.
Forgetting to enable WebSocket message broker with @EnableWebSocketMessageBroker.
Misconfiguring message broker prefixes, causing messages not to route correctly.
Not matching client-side endpoint URLs exactly with server-side registration.

Always ensure your client connects to the exact endpoint URL and uses the correct protocol (STOMP over SockJS).

java

/* Wrong: Missing withSockJS() disables fallback */
registry.addEndpoint("/ws-endpoint");

/* Right: Enables SockJS fallback */
registry.addEndpoint("/ws-endpoint").withSockJS();

📊

Quick Reference

Step	Description	Code Snippet
1	Enable WebSocket message broker	@EnableWebSocketMessageBroker
2	Register STOMP endpoint with SockJS	registry.addEndpoint("/ws-endpoint").withSockJS();
3	Configure message broker prefixes	config.enableSimpleBroker("/topic"); config.setApplicationDestinationPrefixes("/app");
4	Create controller to handle messages	@MessageMapping and @SendTo annotations
5	Connect client to /ws-endpoint using SockJS and STOMP protocol	Use SockJS client library with endpoint URL

✅

Key Takeaways

Use withSockJS() on your endpoint to enable SockJS fallback support.

Annotate your config class with @EnableWebSocketMessageBroker to activate WebSocket messaging.

Match client endpoint URLs exactly with server registration for successful connections.

Configure message broker prefixes correctly to route messages between client and server.

Test fallback by disabling native WebSocket support in your browser to ensure SockJS works.