You're browsing the documentation for v3.x. For v2.x, click here.

Server Initialization

Once you have installed the Socket.IO server library, you can now init the server. The complete list of options can be found here.

Syntax

CommonJS

const httpServer = require("http").createServer();
const io = require("socket.io")(httpServer, {
// ...
});

io.on("connection", (socket) => {
// ...
});

httpServer.listen(3000);

ES modules

Please see here for enabling ECMAScript modules in your Node.js project.

import { createServer } from "http";
import { Server } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
// ...
});

io.on("connection", (socket) => {
// ...
});

httpServer.listen(3000);

TypeScript

Socket.IO has now first-class support for TypeScript:

import { createServer } from "http";
import { Server, Socket } from "socket.io";

const httpServer = createServer();
const io = new Server(httpServer, {
// ...
});

io.on("connection", (socket: Socket) => {
// ...
});

httpServer.listen(3000);

Initialization

Standalone

const options = { /* ... */ };
const io = require('socket.io')(options);

io.on('connection', socket => { /* ... */ });

io.listen(3000);

You can also pass the port as the first argument:

const options = { /* ... */ };
const io = require('socket.io')(3000, options);

io.on('connection', socket => { /* ... */ });

This implicitly starts a Node.js HTTP server, which can be accessed through io.httpServer.

Attached to an existing HTTP server

const server = require('http').createServer();
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

With HTTPS:

const fs = require('fs');
const server = require('https').createServer({
key: fs.readFileSync('/tmp/key.pem'),
cert: fs.readFileSync('/tmp/cert.pem')
});
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

With Express

const app = require('express')();
const server = require('http').createServer(app);
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

More information here.

With Koa

const app = require('koa')();
const server = require('http').createServer(app.callback());
const options = { /* ... */ };
const io = require('socket.io')(server, options);

io.on('connection', socket => { /* ... */ });

server.listen(3000);

More information here.

Notable options

The complete list of options can be found here. Here are those which you will most likely use:

maxHttpBufferSize option

Default value: 1e6

This defines how many bytes a message can be, before closing the socket. It defaults to 1e6 (1MB). You may increase or decrement this value depending on your needs.

const io = require('socket.io')({
maxHttpBufferSize: 1e8
});

It matches the maxPayload option of the ws package.

Caught a mistake? Edit this page on GitHub