PushFlo

Documentation

Everything you need to add real-time features to your serverless app.

Why This Exists

Serverless platforms like Vercel, Netlify, and Cloudflare Workers are amazing for building modern web applications. But they have a fundamental limitation: they can't hold persistent WebSocket connections.

Your serverless function executes, returns a response, and terminates. There's no process running to maintain a WebSocket connection with your user's browser.

PushFlo solves this by running persistent WebSocket servers on the edge. Your serverless function sends messages to our REST API, and we deliver them to your connected users in real-time.

5-Minute Quickstart

Get real-time updates working in your app with two code snippets.

Step 1: Install the SDK

Install the official PushFlo SDK from npm.

Terminalbash
npm install @pushflodev/sdk

Step 2: Subscribe in the browser

Initialize the client and subscribe to a channel.

app/dashboard/page.tsxtypescript
import { PushFloClient } from '@pushflodev/sdk';

// Initialize with your publish key
const client = new PushFloClient({
  publishKey: 'pub_xxxxxxxxxxxxx',
});

// Connect and subscribe to a channel
client.connect();

const subscription = client.subscribe('orders:user-123', {
  onMessage: (message) => {
    console.log('Order status:', message.content);
    // Update your UI here
  },
  onSubscribed: () => console.log('Subscribed!'),
});

// Clean up when component unmounts
// subscription.unsubscribe();
// client.disconnect();

Step 3: Publish from your server

Send messages from your API route or serverless function.

app/api/orders/[id]/route.tstypescript
import { PushFloServer } from '@pushflodev/sdk/server';
import { NextResponse } from 'next/server';

const pushflo = new PushFloServer({
  secretKey: 'sec_xxxxxxxxxxxxx',
});

export async function PATCH(request: Request) {
  const { orderId, status, userId } = await request.json();

  // Update your database
  await db.orders.update({ id: orderId, status });

  // Notify the user in real-time
  await pushflo.publish(`orders:user-${userId}`, {
    orderId,
    status,
  }, { eventType: 'order-updated' });

  return NextResponse.json({ success: true });
}

React Hooks (Optional)

Use the built-in React hooks for seamless integration.

app/providers.tsxtypescript
import { PushFloProvider } from '@pushflodev/sdk/react';

export function Providers({ children }) {
  return (
    <PushFloProvider publishKey="pub_xxxxxxxxxxxxx">
      {children}
    </PushFloProvider>
  );
}
app/dashboard/orders.tsxtypescript
import { useChannel } from '@pushflodev/sdk/react';

export function OrderUpdates({ userId }) {
  const { messages, connectionState } = useChannel(`orders:user-${userId}`);

  return (
    <div>
      <p>Status: {connectionState}</p>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.content.status}</div>
      ))}
    </div>
  );
}

Real-World Examples

Order Status Updates

Notify customers when their order ships, arrives, or encounters an issue.

Channel

orders:user-{userId}

Events

order-shippedorder-deliveredorder-delayed

Live Dashboard

Stream metrics and analytics to admin dashboards without polling.

Channel

dashboard:company-{companyId}

Events

metrics-updatealert-triggered

Team Chat

Build real-time chat for teams or customer support.

Channel

chat:room-{roomId}

Events

message-sentuser-typinguser-joined

Game State Sync

Keep multiplayer game state synchronized across all players.

Channel

game:match-{matchId}

Events

player-movedscore-updatedgame-ended

Resources

Everything you need to integrate PushFlo into your project.

Technical Specifications

Message Limits

  • Max message size: 32KB
  • Payload format: JSON only
  • History retention: 1 day (Free) / 3 days (Starter)

Messages exceeding the size limit will be rejected.

Latency

  • p50: <50ms
  • p95: <150ms
  • p99: <300ms

Measured from publish API call to client message receipt.

Message Ordering

  • Per-channel FIFO ordering guaranteed

Messages within a single channel are delivered in the order they were published.

Delivery Semantics

  • At-most-once delivery

Messages are delivered once or not at all. Use message history for guaranteed delivery.

Infrastructure

  • 300+ Cloudflare cities
  • Automatic failover
  • 99.9% uptime SLA (Starter tier)

Deployed globally on Cloudflare's edge network.

Reconnection

  • Automatic reconnection
  • Exponential backoff (1s initial, 30s max)
  • Message replay on reconnect

The client SDK handles disconnections automatically.

Ready to get started?

Create a free account and start sending real-time messages.