AngularJS Socket.IO Integration

Common errors

• Error: [$injector:modulerr] Failed to instantiate module btford.socket-io

  cause The `btford.socket-io` module definition file (`socket.js` from the bower component) was not loaded into the HTML.
  fix Ensure `<script src="path/to/bower_components/angular-socket-io/socket.js"></script>` is included in your HTML *after* AngularJS and *before* your main application scripts.

• TypeError: io is not a function

  cause The Socket.IO client library (`socket.io.js`) was not loaded before `angular-socket-io` attempts to use the global `io` object.
  fix Add `<script src="/socket.io/socket.io.js"></script>` to your HTML, making sure it loads *before* `angular-socket-io.js`.

• Error: [$injector:unpr] Unknown provider: mySocketProvider

  cause The custom `mySocket` factory (or any other factory/service you create using `socketFactory`) was not properly defined, or the AngularJS module containing its definition was not loaded as a dependency in the module where `mySocket` is being injected.
  fix Verify that your `mySocket` factory is defined in an AngularJS module that is a dependency of the module where `mySocket` is being used, and that the file containing its definition is loaded correctly in your HTML.

Warnings

• breaking The `angular-socket-io` package is built exclusively for AngularJS (1.x) and is fundamentally incompatible with modern Angular (2+), React, Vue, or other contemporary JavaScript frameworks. Attempting to use it in these environments will lead to module resolution failures and runtime errors due to its reliance on AngularJS's dependency injection system and global scope. This package also relies on Bower for dependency management, which is deprecated, making direct installation via npm or yarn problematic without specific configuration or shims.
  Fix: For modern Angular, use `ngx-socket-io`. For other frameworks, use the official `socket.io-client` library directly. This package is not suitable for modern web development.
• gotcha This package requires the Socket.IO client library (`socket.io.js`) to be manually loaded in the browser, typically via a `<script>` tag. It assumes the global `io` object is available. If `socket.io.js` is not loaded before `angular-socket-io.js`, the `socketFactory` will fail to initialize, resulting in `TypeError` or `ReferenceError` related to `io` being undefined.
  Fix: Ensure `<script src="/socket.io/socket.io.js"></script>` is included in your HTML *before* `angular-socket-io.js` and any of your application scripts that use it.
• deprecated The entire package is considered deprecated and effectively abandoned due to its reliance on AngularJS (which is in long-term support but not actively developed for new features) and the Bower package manager. It does not support ESM, TypeScript, or modern build processes. There is no active maintenance, security updates, or new feature development.
  Fix: Migrate to a modern framework and use `socket.io-client` directly or a framework-specific wrapper (e.g., `ngx-socket-io` for Angular). Consider this package for legacy AngularJS applications only.
• gotcha Event forwarding using `socket.forward` and `$scope.$on('socket:eventName', ...)` relies on AngularJS's digest cycle. If Socket.IO events fire rapidly or outside of Angular's control, changes to `$scope` properties within the `$on` handler might not update the UI immediately without manual calls to `$scope.$apply()` or `$rootScope.$apply()`, which can lead to performance issues or unexpected behavior. Overuse of `$apply()` can also lead to 'digest already in progress' errors.
  Fix: Ensure that any state changes within `$scope.$on` handlers are safely wrapped in `$scope.$apply()` if necessary (e.g., `if (!$scope.$$phase) $scope.$apply()`), or use `ng-model` bindings that trigger a digest. For high-frequency events, reconsider the event forwarding strategy or debounce updates.

Install

• npm install angular-socket-io npm
• yarn add angular-socket-io yarn
• pnpm add angular-socket-io pnpm

Imports

• btford.socket-io
  wrong:

  import { btford.socket-io } from 'angular-socket-io'

  correct:

  angular.module('myApp', ['btford.socket-io'])

  This is the AngularJS module name that must be declared as a dependency in your application's `angular.module()` call. It is not an ES module or CommonJS import.
• socketFactory
  wrong:

  const socketFactory = require('angular-socket-io').socketFactory

  correct:

  angular.module('myApp').factory('mySocket', function (socketFactory) { /* ... */ })

  The `socketFactory` is an AngularJS service provider, injected into other services, controllers, or factories within your AngularJS application's dependency injection system.
• socket.forward

  mySocket.forward('eventName', $scope)

  A method on the `socket` instance created by `socketFactory`. It forwards Socket.IO events to AngularJS's `$scope` or `$rootScope` event system, allowing listening via `$scope.$on`.

Quickstart

Demonstrates how to configure `angular-socket-io` as an AngularJS factory, instantiate a `socketFactory` instance, forward Socket.IO events to AngularJS scopes, and use the socket instance in a controller to send and receive messages.

// First, ensure AngularJS and the Socket.IO client library are loaded in your HTML:
// <script src="path/to/angular.min.js"></script>
// <script src="/socket.io/socket.io.js"></script>
// <script src="path/to/bower_components/angular-socket-io/socket.js"></script>

// Define your main AngularJS module and add 'btford.socket-io' as a dependency
angular.module('myApp', [
  'btford.socket-io',
  'myApp.MyCtrl' // Assuming you have a controller named MyCtrl
])
.factory('mySocket', function (socketFactory) {
  // Instantiate a socket. This can be configured with 'ioSocket' for custom connections.
  var mySocket = socketFactory();

  // Optionally, forward socket events to AngularJS's event system.
  // This makes 'error' events available via $scope.$on('socket:error', ...)
  mySocket.forward('error');
  // Forward multiple events, here 'connect' and 'disconnect' to $rootScope by default (null scope)
  mySocket.forward(['connect', 'disconnect'], null);

  return mySocket;
})
.controller('MyCtrl', function ($scope, mySocket) {
  // Use the injected socket instance
  $scope.messages = [];
  $scope.inputMessage = '';

  // Listen for a custom 'message' event from the server
  mySocket.on('message', function (data) {
    $scope.messages.push(data);
  });

  // Function to send a message to the server
  $scope.sendMessage = function () {
    if ($scope.inputMessage) {
      mySocket.emit('sendMessage', { text: $scope.inputMessage, timestamp: new Date() });
      $scope.inputMessage = ''; // Clear input after sending
    }
  };

  // Listen for forwarded socket error events within this specific scope
  $scope.$on('socket:error', function (ev, data) {
    console.error('Socket Error:', data);
    $scope.messages.push({ text: `Error: ${data.message || 'Unknown error'}`, type: 'error' });
  });

  // Example of emitting an event when the controller initializes
  mySocket.emit('joinRoom', { room: 'general' });
});