npm install syncity



Quick Start 🔥
Kickstart your project in just a few lines:



import SyncityClient from 'syncity-client';

// Initialize the client with your server URL
const syncity = new SyncityClient({ host: 'http://your-server.com' });

// Listen for the initial state
syncity.on('init', (state) => {
  console.log('Initial state:', state);
});

// Listen for state updates
syncity.on('stateUpdate', (state) => {
  console.log('Updated state:', state);
});

// Update the state (include a timestamp for conflict resolution)
syncity.updateState({ counter: 1, timestamp: Date.now() });


Framework Integrations 🛠️
React
Syncity Context Provider Example:


// SyncityProvider.js
import React, { createContext, useEffect, useState } from 'react';
import SyncityClient from 'syncity-client';

export const SyncityContext = createContext();

export function SyncityProvider({ children, host }) {
  const [state, setState] = useState({});
  const [syncity, setSyncity] = useState(null);

  useEffect(() => {
    const client = new SyncityClient({ host });
    setSyncity(client);
    client.on('init', setState);
    client.on('stateUpdate', setState);
    return () => client.disconnect();
  }, [host]);

  return (
    <SyncityContext.Provider value={{ state, syncity }}>
      {children}
    </SyncityContext.Provider>
  );
}
Example Component:


// Counter.js
import React, { useContext } from 'react';
import { SyncityContext } from './SyncityProvider';

function Counter() {
  const { state, syncity } = useContext(SyncityContext);

  const increment = () => {
    const newValue = (state.counter || 0) + 1;
    syncity.updateState({ counter: newValue, timestamp: Date.now() });
  };

  return (
    <div>
      <h2>Counter: {state.counter || 0}</h2>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

export default Counter;
Angular
Syncity Service Example:


// syncity.service.ts
import { Injectable } from '@angular/core';
import SyncityClient from 'syncity-client';
import { BehaviorSubject } from 'rxjs';

@Injectable({
  providedIn: 'root'
})
export class SyncityService {
  private client: any;
  public state$ = new BehaviorSubject<any>({});

  constructor() {
    this.client = new SyncityClient({ host: 'http://your-server.com' });
    this.client.on('init', (state: any) => this.state$.next(state));
    this.client.on('stateUpdate', (state: any) => this.state$.next(state));
  }

  updateState(payload: any) {
    payload.timestamp = Date.now();
    this.client.updateState(payload);
  }
}
Angular Component Example:


// counter.component.ts
import { Component, OnInit } from '@angular/core';
import { SyncityService } from './syncity.service';

@Component({
  selector: 'app-counter',
  template: `
    <div>
      <h2>Counter: {{ state?.counter || 0 }}</h2>
      <button (click)="increment()">Increment</button>
    </div>
  `
})
export class CounterComponent implements OnInit {
  state: any;

  constructor(private syncityService: SyncityService) {}

  ngOnInit() {
    this.syncityService.state$.subscribe(state => this.state = state);
  }

  increment() {
    const newValue = (this.state.counter || 0) + 1;
    this.syncityService.updateState({ counter: newValue });
  }
}


Node.js
Server-Side Example:


// server.js
const SyncityClient = require('syncity-client');

const syncity = new SyncityClient({ host: 'http://your-server.com' });

syncity.on('init', (state) => {
  console.log('Initial state:', state);
});

syncity.on('stateUpdate', (state) => {
  console.log('Updated state:', state);
});

// Update state example
syncity.updateState({ serverCounter: 100, timestamp: Date.now() });
Next.js
Next.js Page Example:


// pages/index.js
import { useEffect, useState } from 'react';
import SyncityClient from 'syncity-client';

export default function Home() {
  const [state, setState] = useState({});

  useEffect(() => {
    const syncity = new SyncityClient({ host: 'http://your-server.com' });
    syncity.on('init', setState);
    syncity.on('stateUpdate', setState);

    return () => syncity.disconnect();
  }, []);

  const increment = () => {
    const newValue = (state.counter || 0) + 1;
    syncity.updateState({ counter: newValue, timestamp: Date.now() });
  };

  return (
    <div>
      <h1>Welcome to Syncity</h1>
      <p>Counter: {state.counter || 0}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}
API Reference ⚡
Initialize Client:


new SyncityClient(options)
options.host: URL of your Syncity server.
Subscribe to Events:


syncity.on(event, callback)
init – Fired on initial state load.
stateUpdate – Fired on state updates.
error – Fired on errors.
Update State:



syncity.updateState(payload)
payload: An object containing your update data plus a timestamp for conflict resolution.
Plugin Architecture 🧩
Syncity is built to be lightweight and extensible. Create plugins to add custom functionality—like logging, analytics, or enhanced conflict resolution—without modifying the core. See our Plugin Guide for more details.

Comparisons 🔍
Syncity vs. Redux/Context API:
Redux and Context API manage local state but require additional libraries for real-time synchronization. Syncity provides both in a unified package.

Syncity vs. Firebase/Firestore:
Instead of relying on a backend-as-a-service, Syncity offers a self-hosted, unified API across client and server for full control.

Syncity vs. Collaborative Libraries (Yjs, ShareDB):
Beyond real-time editing, Syncity includes offline-first support and plugin extensibility, making it a comprehensive state synchronization solution.

Contributing 🤝
We welcome contributions!

Fork the repository: GitHub Repo
Read our guidelines: See CONTRIBUTING.md
Submit PRs or open issues: Help us improve Syncity and join our growing community.
License 📜
Syncity is licensed under the MIT License.

Get in Touch 📬
GitHub Repository: https://github.com/learnXplor/syncity
npm Package: https://www.npmjs.com/package/syncity
linkedin : www.linkedin.com/in/pallav-singh-developer