Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js net.createConnection() method
Reference for net.createConnection() and net.connect() in Node.js: open TCP or IPC client connections, options, events, timeouts and common errors.
net.createConnection() opens a client connection and returns a net.Socket that is already connecting. net.connect() is an identical alias. Use it for TCP connections (port and host) or for local IPC connections (path).
The connection is asynchronous. The function returns immediately; the 'connect' event fires once the handshake succeeds, and an 'error' event fires if it fails. You can write to the socket right away: data is buffered until the connection is open.
import net from 'node:net'; const socket = net.createConnection({ port: 3000, host: '127.0.0.1' }, () => { socket.write('hello'); });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
net.createConnection(options: object, connectListener?: () => void): net.Socket net.createConnection(port: number, host?: string, connectListener?: () => void): net.Socket net.createConnection(path: string, connectListener?: () => void): net.Socket
| Name | Description |
|---|---|
port |
TCP port to connect to (required for TCP). |
host |
Host name or IP address. Default 'localhost'. |
path |
Unix domain socket path or Windows named pipe. Used instead of port and host. |
localAddress, localPort |
Bind the outgoing side to a specific local address or port. |
family |
4 or 6 to force an address family; 0 (default) allows both. |
timeout |
Idle timeout in milliseconds. Fires the 'timeout' event; it does not close the socket. |
allowHalfOpen |
Default false. With true, the socket stays open for writing after the other side ends. |
noDelay, keepAlive, keepAliveInitialDelay |
Same meaning as for net.createServer(). |
autoSelectFamily, autoSelectFamilyAttemptTimeout |
Try several resolved addresses in turn, see Happy Eyeballs options. |
lookup |
Custom DNS lookup function with the signature of dns.lookup(). |
signal |
An AbortSignal that destroys the socket when aborted. |
connectListener |
Added once as a listener for 'connect'. |
Returns: a net.Socket.
Errors and edge cases: a missing or out-of-range port throws ERR_SOCKET_BAD_PORT synchronously. Network failures are emitted as 'error': ECONNREFUSED (nothing is listening), ENOTFOUND (the name did not resolve), ETIMEDOUT, ECONNRESET, EHOSTUNREACH.
Usage notes
- Attach an
'error'listener before anything else. Without one, a refused connection crashes the process. 'connect'fires once. Do not use it as a "ready to read" signal; data events follow independently.timeoutonly reports. Handle'timeout'and callsocket.destroy()(orend()) yourself.localhostcan resolve to::1and127.0.0.1. If the server listens on only one of them, connecting by name can fail unlessautoSelectFamilyis on (the default since Node 20). Use an explicit IP in tests.- Reusing the socket. A closed socket cannot be reconnected reliably; create a new one per connection attempt.
- Promises. Use
await once(socket, 'connect')fromnode:events; it also rejects if'error'fires first. - Alias.
net.connect()andnet.createConnection()are the same function; pick one and stay consistent.