Mastering Local-First Architecture: Building Real-Time Bidirectional Data Sync with Yjs and Node.js WebSockets on a VPS

Introduction to the Local-First Revolution

For over a decade, the cloud-first paradigm has dominated software development. Applications have relied heavily on a continuous network connection to function, treating the local device as a thin client. However, this approach introduces latency, vulnerability to network outages, and complex state management on the client side. Enter Local-First Architecture.

Local-first software combines the best of both worlds: the responsiveness and autonomy of local applications with the collaborative power of the cloud. In a local-first application, the primary copy of the data lives on the user's local device (IndexedDB, SQLite, or local storage). The application remains fully functional offline. When a network connection is available, data synchronizes seamlessly and bidirectionally in real time with other peers or servers.

In this technical guide, we will explore how to design and deploy a production-ready synchronization backend for a local-first application. We will utilize Yjs, a high-performance Conflict-free Replicated Data Type (CRDT) ecosystem, paired with a custom Node.js WebSocket server, and deploy the entire infrastructure onto a Virtual Private Server (VPS).

The Core Tech Stack: Why Yjs and WebSockets?

Building bidirectional sync requires solving a foundational computer science challenge: conflict resolution. If User A and User B modify the same document simultaneously while offline, how does the system merge their changes without destroying data when they reconnect?

The Power of CRDTs and Yjs

Traditional systems use Operational Transformation (OT), which requires a centralized, authoritative server to sequence operations. Local-first architectures lean heavily on Conflict-free Replicated Data Types (CRDTs). CRDTs allow mathematical merging of concurrent edits without requiring a central coordinator to determine the 'correct' state.

Yjs stands out as the premier CRDT implementation in the JavaScript ecosystem because:

Performance: It uses highly optimized internal structures, making it orders of magnitude faster than alternative CRDT libraries.
Network Agnostic: Yjs handles the data structures and conflict resolution, leaving the transport layer entirely up to you (WebSockets, WebRTC, or even matrix protocols).
Rich Ecosystem: It provides native bindings for popular text editors (ProseMirror, Monaco, Quill) and shared data types (Y.Map, Y.Array, Y.Text).

WebSockets for Real-Time Transport

While WebRTC is excellent for pure peer-to-peer (P2P) setups, a production business application usually requires a reliable central relay and a persistent storage backup. Node.js with WebSockets provides a lightweight, highly scalable, and persistent bi-directional communication channel perfectly suited to stream Yjs update binary arrays.

---

System Architecture Overview

Before diving into the code, it is vital to understand how data flows through our local-first ecosystem. The architecture consists of three core layers:

Client Layer: The application UI interacts directly with a local Yjs Document (Y.Doc). Changes are saved instantly to a local database (like IndexedDB) and emitted as binary update events via a WebSocket provider.
Transport Layer: A Node.js server running a WebSocket server (via the ws library) receives these binary updates and broadcasts them to all other connected clients subscribing to the same document ID.
Persistence Layer: The Node.js server periodically or reactively flushes the accumulated Yjs document state to a persistent database (e.g., PostgreSQL, Redis, or flat-file storage) on the VPS, ensuring that new clients can bootstrap their state quickly.

Note: In local-first systems, the server does not necessarily need to inspect or modify the application data; its primary responsibility is acting as a highly efficient, reliable communication broker and persistence agent.

---

Step-by-Step Implementation

1. Setting Up the Node.js WebSocket Server

First, we initialize a new Node.js project and install the required dependencies. We will use yjs along with y-websocket, which provides production-ready server utilities.

npm init -y
npm install yjs y-websocket ws dotenv

Next, we create our server entry point, server.js. This script initializes a standard HTTP server, attaches a WebSocket server, and integrates the Yjs sync protocol handlers.

const WebSocket = require('ws');
const http = require('http');
const setupWSConnection = require('y-websocket/bin/utils').setupWSConnection;

const port = process.env.PORT || 1234;
const server = http.createServer((request, response) => {
  response.writeHead(200, { 'Content-Type': 'text/plain' });
  response.end('Yjs Sync Server Running');
});

const wss = new WebSocket.Server({ server });

wss.on('connection', (conn, req) => {
  // The setupWSConnection function handles document room isolation and synchronization
  setupWSConnection(conn, req, {
    gc: true, // Enable garbage collection to keep memory usage low
  });
});

server.listen(port, () => {
  console.log(`Synchronization server is running on port ${port}`);
});

2. Configuring Client-Side Synchronization

On the client side, initializing the connection requires binding your local Y.Doc to both a persistent local storage mechanism and our newly created WebSocket provider.

import * as Y from 'yjs';
import { WebSocketProvider } from 'y-websocket';
import { IndexeddbPersistence } from 'y-indexeddb';

// 1. Initialize the Yjs Document
const doc = new Y.Doc();
const roomName = 'business-document-xyz';

// 2. Persist state locally immediately to handle offline mode
const indexeddbProvider = new IndexeddbPersistence(roomName, doc);

// 3. Establish WebSocket connection for real-time bidirectional sync
const wsProvider = new WebSocketProvider('ws://localhost:1234', roomName, doc);

indexeddbProvider.on('synced', () => {
  console.log('Local database loaded. App ready for offline use.');
});

wsProvider.on('status', event => {
  console.log(`WebSocket Connection Status: ${event.status}`); // 'connected' or 'disconnected'
});

---

Deploying to a VPS: Production Hardening

Moving from a local environment to a public-facing Virtual Private Server (VPS) requires robust configurations around security, process management, and reverse proxying.

Process Management with PM2

To ensure your Node.js server automatically restarts after a crash or system reboot, utilize PM2. Install it globally on your VPS and start the application:

sudo npm install -g pm2
pm2 start server.js --name "yjs-sync-server"
pm2 startup
pm2 save

Configuring Nginx as a Reverse Proxy with SSL

WebSockets require careful proxy handling, especially for securing connections via wss:// (WebSocket Secure). Below is an optimized Nginx configuration segment to place inside your site configuration block (/etc/nginx/sites-available/default):

server {
    server_name sync.yourdomain.com;

    location / {
        proxy_pass http://localhost:1234;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

Crucial Configuration Details: The proxy_read_timeout and proxy_send_timeout directives are bumped to 24 hours (86400 seconds). This prevents Nginx from prematurely dropping idle WebSocket connections when users are reading documents without actively making edits.

Finally, always secure the connection by running sudo certbot --nginx to acquire free SSL certificates from Let's Encrypt. Operating over wss:// is mandatory to bypass restrictive enterprise firewalls that routinely drop unencrypted WebSocket traffic.

---

Performance and Scaling Considerations

While a single modern VPS can comfortably handle thousands of concurrent WebSocket connections due to Yjs's lean binary footprint, scaling horizontally requires a message broker. If your user base expands globally, consider implementing a Redis Pub/Sub architecture to bridge multiple Node.js instances, ensuring updates received on Server A are instantly broadcast to clients connected to Server B.

Conclusion

Transitioning to a Local-First architecture drastically enhances user experience by eliminating loading spinners, enabling resilient offline collaboration, and reducing server compute overhead. By combining the conflict-free merging capabilities of Yjs with a streamlined Node.js WebSocket backend on your own VPS, you build a powerful, self-hosted data infrastructure capable of supporting modern, high-performance business applications.