Socket.io bindings for Vue.js 2 and Vuex (inspired by Vue-Socket.io)
:warning: The alpha version of v5 (with Vue 3 support) has been released. Your feedback would be appreciated here
$socket.connected
and $socket.disconnected
socket.io
events inside componentssocket.io
eventssocket.io-client
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
---|---|---|---|---|---|
38+ :heavy_check_mark: | 13+ :heavy_check_mark: | 8+ :heavy_check_mark: | 25+ :heavy_check_mark: | 12+ :heavy_check_mark: | 11+ :heavy_check_mark: |
We support only browsers with global usage statistics greater than 1% and last 2 version of each browser (but not dead browsers). Library may work in older browser as well, but we don't guarantee that. You may need addition polyfills to make it work.
I was using Vue-Socket.io
for few months. I've liked the idea, but the more I used it the more I faced with bugs, outdated documentation, lack of support, absence of tests, and a huge amount of issues :disappointed:. That slowed down development of the product I was working on. So I ended up with a decision to create my own fork with all the desirable stuff (features/fixes/tests/support/CI checks etc). That's how vue-socket.io-extended
was born.
If you'd like to help - create an issue or PR. I will be glad to see any contribution. Let's make the world a better place :heart:
You must have a running Socket.IO server before starting any Vue/Socket.IO project! Instructions on how to build a Node/Socket.IO server are found here.
>=2.X
>=2.X
>=2.X
(optional)npm install vue-socket.io-extended socket.io-client
import VueSocketIOExt from 'vue-socket.io-extended';
import { io } from 'socket.io-client';
const socket = io('http://socketserver.com:1923');
Vue.use(VueSocketIOExt, socket);
Note: you have to pass instance of socket.io-client
as second argument to prevent library duplication. Read more here.
<script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/socket.io-client/dist/socket.io.slim.js"></script>
<script src="https://cdn.jsdelivr.net/npm/vue-socket.io-extended"></script>
<script>
var socket = io('http://socketserver.com:1923');
Vue.use(VueSocketIOExt, socket);
</script>
Define your listeners under sockets
section, and they will listen corresponding socket.io
events automatically.
new Vue({
sockets: {
connect() {
console.log('socket connected')
},
customEmit(val) {
console.log('this method was fired by the socket server. eg: io.emit("customEmit", data)')
}
},
methods: {
clickButton(val) {
// this.$socket.client is `socket.io-client` instance
this.$socket.client.emit('emit_method', val);
}
}
})
Note: Don't use arrow functions for methods or listeners if you are going to emit socket.io
events inside. You will end up with using incorrect this
. More info about this here
There is a way to create listeners dynamically, in case you need to start listening only on some condition.
// creating event listener
this.$socket.$subscribe('event_name', payload => {
console.log(payload)
});
// removing existing listener
this.$socket.$unsubscribe('event_name');
As an alternative, feel free to attach events directly to socket.io client, but keep in mind that you'd need to pass the same function to .off(event_name, fn)
that you passed to .on(event_name, fn)
in order to unsubscribe properly. Otherwise, it won't work as you expect.
export default {
methods: {
onEventName(params) {
console.log('`eventName` has fired with:', params)
},
},
mounted() {
// subscribe
this.$socket.client.on('eventName', this.onEventName) // <-- this.onEventName here
},
beforeDestroy() {
// unsubscribe
this.$socket.client.off('eventName', this.onEventName) // <-- this.onEventName here
},
}
Important: Every dynamic subscription should have appropriate unsubscription. Or else, you'd experience an event firing multiple times. Moreover, unsubscribed leftovers might cause memory leaks.
$socket.connected
and $socket.diconnected
are reactive. That means you can use them in expressions
<template>
<div>
<span>{{ $socket.connected ? 'Connected' : 'Disconnected' }}</span>
</div>
</template>
Or conditions
<template>
<span
class="notification"
v-if="$socket.disconnected"
>
You are disconnected
</span>
</template>
Or computed properties, methods and hooks. Treat them as computed properties that are available in all components
To set up Vuex integration just pass the store as the third argument. In a Vue CLI project, you might do this in the src/main.js
file. Example:
import VueSocketIOExt from 'vue-socket.io-extended';
import { io } from 'socket.io-client';
import store from './store'
const socket = io('http://socketserver.com:1923');
Vue.use(VueSocketIOExt, socket, { store });
Mutations and actions will be dispatched or committed automatically in the Vuex store when a socket event arrives. A mutation or action must follow the naming convention below to recognize and handle a socket event.
SOCKET_
prefix and continue with an uppercase version of the eventsocket_
prefix and continue with camelcase version of the eventServer Event | Mutation | Action |
---|---|---|
chat message |
SOCKET_CHAT MESSAGE |
socket_chatMessage |
chat_message |
SOCKET_CHAT_MESSAGE |
socket_chatMessage |
chatMessage |
SOCKET_CHATMESSAGE |
socket_chatMessage |
CHAT_MESSAGE |
SOCKET_CHAT_MESSAGE |
socket_chatMessage |
Check the Configuration section if you'd like to use a custom transformation.
Check the Migration from VueSocketIO section if you want to keep actions names in UPPER_CASE.
// In this example we have a socket.io server that sends message ID when it arrives
// so to get entire body of the message we need to make AJAX call the server
import Vue from 'vue'
import Vuex from 'vuex'
// `MessagesAPI.downloadMessageById` is an async function (goes to backend through REST Api and fetches all message data)
import MessagesAPI from './api/message'
Vue.use(Vuex);
export default new Vuex.Store({
state: {
// we store messages as a dictionary for easier access and interaction
// @see https://hackernoon.com/shape-your-redux-store-like-your-database-98faa4754fd5
messages: {},
messagesOrder: []
},
mutations: {
NEW_MESSAGE(state, message) {
state.messages[message.id] = message;
state.messagesOrder.push(message.id);
}
},
actions: {
socket_userMessage ({ dispatch, commit }, messageId) { // <-- this action is triggered when `user_message` is emmited on the server
return MessagesAPI.downloadMessageById(messageId).then((message) => {
commit('NEW_MESSAGE', message);
})
}
}
})
Events can be sent to the Socket.IO server by calling this._vm.$socket.client.emit
from a Vuex mutation or action. Mutation or action names are not subject to the same naming requirements as above. More then one argument can be included. All serializable data structures are supported, including Buffer.
actions: {
emitSocketEvent(data) {
this._vm.$socket.client.emit('eventName', data);
this._vm.$socket.client.emit('with-binary', 1, '2', { 3: '4', 5: new Buffer(6) });
}
}
Namespaced modules are supported out-of-the-box. Any appropriately-named mutation or action should work regardless of whether it's in a module or in the main Vuex store.
import Vue from 'vue'
import Vuex from 'vuex'
Vue.use(Vuex);
const messages = {
state: {
messages: []
},
mutations: {
SOCKET_CHAT_MESSAGE(state, message) {
state.messages.push(message);
}
},
actions: {
socket_chatMessage() {
console.log('this action will be called');
}
},
};
const notifications = {
state: {
notifications: []
},
mutations: {
SOCKET_CHAT_MESSAGE(state, message) {
state.notifications.push({ type: 'message', payload: message });
}
},
};
export default new Vuex.Store({
modules: {
messages,
notifications,
}
})
The above code will:
SOCKET_CHAT_MESSAGE
mutation in the messages
moduleSOCKET_CHAT_MESSAGE
mutation in the notification
modulesocket_chatMessage
action in the messages
moduleRequired: ECMAScript stage 1 decorators.
If you use Babel, babel-plugin-transform-decorators-legacy is needed.
If you use TypeScript, enable --experimentalDecorators
flag.
It does not support the stage 2 decorators yet since mainstream transpilers still transpile to the old decorators.
We provide @Socket()
decorator for users of class-style Vue components. By default, @Socket()
decorator listens the same event as decorated method name but you can use custom name by passing a string inside decorator e.g. @Socket('custom_event')
.
Check the example below:
<!-- App.vue -->
<script>
import Vue from 'vue'
import Component from 'vue-class-component'
import { Socket } from 'vue-socket.io-extended'
@Component({})
export default class App extends Vue {
@Socket() // --> listens to the event by method name, e.g. `connect`
connect () {
console.log('connection established');
}
@Socket('tweet') // --> listens to the event with given name, e.g. `tweet`
onTweet (tweetInfo) {
// do something with `tweetInfo`
}
}
</script>
The key point here is to disable SSR for the plugin as it will crash otherwise. It's a well-know issue and we are going to fix it. Thanks @ll931217 for investigation.
1. Create plugin:
// ~/plugins/socket.io.js
import Vue from 'vue';
import { io } from 'socket.io-client';
import VueSocketIOExt from 'vue-socket.io-extended';
const socket = io('http://localhost:3000');
export default ({ store }) => {
Vue.use(VueSocketIOExt, socket, { store });
}
2. Then register it:
// nuxt.config.js
module.exports = {
//...,
plugins: [
//...,
{
src: '~/plugins/socket.io.js',
ssr: false, // <-- this line is required
},
]
}
Register vue-socket.io-extended with a boot file and disable server side rendering
1. Create bootfile:
// ~/boot/socket.io.js
import { io } from 'socket.io-client';
import VueSocketIOExt from 'vue-socket.io-extended';
const socket = io('http://localhost:3000');
export default async ({ store, Vue }) => {
Vue.use(VueSocketIOExt, socket, { store })
}
2. Then register it:
// quasar.conf.js
module.exports = function (ctx) {
return {
//...,
boot: [
//...,
{
path: 'socket.io',
server: false,
},
]
}
};
In addition to store instance, vue-socket.io-extended
accepts other options.
Here they are:
Option | Type | Default | Description |
---|---|---|---|
store |
Object |
undefined |
Vuex store instance, enables vuex integration |
actionPrefix |
String |
'socket_' |
Prepend to event name while converting event to action. Empty string disables prefixing |
mutationPrefix |
String |
'SOCKET_' |
Prepend to event name while converting event to mutation. Empty string disables prefixing |
eventToMutationTransformer |
Function string => string |
uppercase function | Determines how event name converted to mutation |
eventToActionTransformer |
Function string => string |
camelcase function | Determines how event name converted to action |
eventMapping | Function socket => string |
Map your event from socket event data |
FYI: You can always access default plugin options if you need it (e.g. re-use default eventToActionTransformer
function):
import VueSocketIOExt from 'vue-socket.io-extended';
VueSocketIOExt.defaults // -> { actionPrefix: '...', mutationPrefix: '...', ... }
For everyone who has migrated from old package VueSocketIO to this new one on existing project.
You need to re-define 2 parameters, in order to use existing store actions without changes (e.g. SOCKET_EVENT_NAME
).
import VueSocketIO from 'vue-socket.io-extended';
import { io } from 'socket.io-client';
const ioInstance = io('https://hostname/path', {
reconnection: true,
reconnectionDelay: 500,
maxReconnectionAttempts: Infinity
});
Vue.use(VueSocketIO, ioInstance, {
store, // vuex store instance
actionPrefix: 'SOCKET_', // (1) keep prefix in uppercase
eventToActionTransformer: (actionName) => actionName // (2) cancel camelcasing
});
This plugin follows semantic versioning.
We're using GitHub Releases.
We're more than happy to see potential contributions, so don't hesitate. If you have any suggestions, ideas or problems feel free to add new issue, but first please make sure your question does not repeat previous ones.
See the LICENSE file for license rights and limitations (MIT).