Registry / http-networking / phoenix

phoenix

JSON →
library0.9.1jsnpmunverified

The Phoenix JavaScript client provides real-time bidirectional communication capabilities for frontend applications interacting with Phoenix web framework backends. It leverages WebSockets and Phoenix Channels to enable features like chat, live notifications, and collaborative editing. The current stable version, 1.8.5, is released in conjunction with the Phoenix framework, leading to an irregular but consistent release cadence. A key differentiator is its robust channel-based publish/subscribe system, which is tightly integrated with the Elixir/Phoenix ecosystem, offering fault-tolerant and highly concurrent real-time services. It's designed to provide a structured approach to real-time communication, ensuring reliable message delivery and state management between client and server.

npm install phoenix
INSTALL
IMPORT
SIG · PHOENIX
P
phoenix
http-networkingjavascriptv0.9.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Socket
import { Socket } from 'phoenix'
import Socket from 'phoenix'; const { Socket } = require('phoenix');
Socket is the primary entry point for establishing a connection to the Phoenix backend. It is a named export, commonly used in modern JavaScript/TypeScript environments.
Channel
const channel = socket.channel('topic', params);
import { Channel } from 'phoenix';
Channel instances are created via a connected Socket instance (`socket.channel(...)`), not directly imported. Do not attempt to import Channel as a top-level class.
LongPoll
import { LongPoll } from 'phoenix'
LongPoll is a named export available for fallback transport mechanisms when WebSockets are not available or preferred. It's less commonly used directly by applications unless specific fallback logic is required.

This quickstart demonstrates how to establish a WebSocket connection to a Phoenix backend, join a specific channel, send messages to the channel, and handle incoming real-time events.

import { Socket } from "phoenix"; // Replace with your Phoenix server's WebSocket URL, e.g., 'ws://localhost:4000/socket' const socketUrl = "ws://your-phoenix-app.com/socket"; const userToken = process.env.PHOENIX_AUTH_TOKEN ?? ''; // Use env var for auth or actual token // Instantiate a new Socket connection const socket = new Socket(socketUrl, { params: { userToken } }); // Connect to the socket socket.connect(); socket.onOpen(() => console.log("Socket connected successfully!")); socket.onError((error) => console.error("Socket error:", error)); socket.onClose(() => console.log("Socket closed.")); // Join a specific channel, e.g., 'room:lobby' const channel = socket.channel("room:lobby", {}); // Set up event listeners for messages received on this channel channel.on("new_msg", (payload) => { console.log("Received new message:", payload.body); }); channel.on("user_joined", (payload) => { console.log("User joined channel:", payload.username); }); // Attempt to join the channel and handle outcomes channel.join() .receive("ok", ({ messages }) => { console.log("Joined channel successfully! Initial messages:", messages); // Push a message to the channel after successful join channel.push("new_msg", { body: "Hello Phoenix channel!" }) .receive("ok", (msg) => console.log("Message pushed successfully:", msg)) .receive("error", (reasons) => console.error("Failed to push message:", reasons)) .receive("timeout", () => console.warn("Message push timed out.")); }) .receive("error", ({ reason }) => { console.error("Failed to join channel:", reason); }) .receive("timeout", () => { console.warn("Joining channel timed out. Server might be unreachable or slow."); }); // Example of leaving a channel or disconnecting the socket after some time // setTimeout(() => { // channel.leave(); // socket.disconnect(); // console.log("Channel left and socket disconnected after 15 seconds."); // }, 15000);
Debug
Known issues
breakingUpgrading the Phoenix framework from v1.1.x to v1.2.x may require adjustments to the JavaScript client and careful review of the framework's upgrade instructions. While the changelog primarily lists backend changes, tight coupling often means client-side updates are necessary for compatibility or to leverage new features.
fix
Consult the official Phoenix framework 1.1.x to 1.2.x upgrade guide (https://gist.github.com/chrismccord/29100e16d3990469c47f851e3142f766) and thoroughly test client functionality after the upgrade.
affects: >=1.2.0
breakingUpgrading the Phoenix framework from v1.0.x to v1.1.x might introduce incompatibilities with older JavaScript client versions. Although the client-specific API changes are not always detailed in the framework's changelog, major framework updates often necessitate updating the client library and reviewing integration points.
fix
Refer to the Phoenix framework 1.0.x to 1.1.0 upgrade instructions (https://gist.github.com/chrismccord/557ef22e2a03a7992624) and ensure the client library is updated to a compatible version.
affects: >=1.1.0
gotchaThe Phoenix client uses WebSockets for real-time communication. Ensure your WebSocket URL (e.g., `ws://localhost:4000/socket`) is correct, and that your Phoenix backend server is running and configured to accept WebSocket connections on that path and port.
fix
Verify the `socketUrl` passed to the `Socket` constructor matches your Phoenix endpoint's WebSocket configuration. Check server logs for connection errors (e.g., firewall issues, incorrect port).
affects: >=1.0.0
gotchaChannel join requests can be refused by the server due to incorrect topic names, missing or invalid authentication tokens, or server-side authorization policies. Always handle the `receive("error")` callback from `channel.join()` to diagnose specific issues.
fix
Ensure the channel topic string matches a configured topic on your Phoenix backend. Pass necessary authentication tokens in the `params` object when instantiating `Socket` or joining a `Channel`. Review server-side `UserSocket` and `Channel` authorization logic for any rejections.
affects: >=1.0.0
Errors
Common errors & fixes
WebSocket connection to 'ws://localhost:4000/socket' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED
The Phoenix backend server is not running, the WebSocket URL is incorrect, or a firewall is blocking the connection to the specified port.
fix
Start your Phoenix server, verify the `socketUrl` points to the correct address and port, and check firewall settings to ensure the port is open.
channel join 'topic' was refused
The server explicitly rejected the channel join request, commonly due to authentication failure, an invalid channel topic, or a server-side authorization policy preventing the join.
fix
Examine the `reason` payload from the `receive("error", ({ reason }) => ...)` callback for detailed error messages. Verify user authentication, the channel topic name, and review your Phoenix backend's `UserSocket` and `Channel` modules for authorization logic.
channel join 'topic' timed out
The client did not receive an 'ok' or 'error' response from the server within the configured timeout period after attempting to join a channel. This might indicate network issues or an unresponsive server.
fix
Check network connectivity between the client and the Phoenix server. Confirm the Phoenix server is running and not overloaded. The default join timeout can be adjusted in the `channel.join()` call if needed for slower networks.
Upgrade
Version history
0.9.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources