Home Reference Source Repository

NPM

a lightweight module to sync JS objects in realtime across tabs / windows of a browser.

Features

Build Status codecov

NPM

Install

npm i -S localsync

How to use

import localsync from 'localsync'

/** Create an action that will trigger a sync to other tabs. */
const action = (userID, first, last) => ({ userID, first, last })

/** Create a handler that will run on all tabs that did not trigger the sync. */
const handler = (value, old, url) => {
  console.info(`Another tab at url ${url} switched user from "${old.first} ${old.last}" to "${value.first} ${value.last}".`)
  // do something with value.userID
}

/** Create a synchronizer. localsync supports N number of synchronizers for different things across your app. */
const usersync = localsync('user', action, handler)

/** Start synchronizing. */
usersync.start()

/** IE / Edge do not support local storage across multiple tabs. localsync will automatically fallback to a cookie polling mechanism here. You don't need to do anything else. */
if(usersync.isFallback)
  console.warn('browser doesnt support local storage synchronization, falling back to cookie synchronization.')

/** Trigger an action that will get handled on other tabs. */
usersync.trigger(1, 'jimmy', 'john')

setTimeout(() => {
  /** Trigger another action in 5 seconds. */
  usersync.trigger(2, 'jane', 'wonka')
}, 5000)

setTimeout(() => {
  /** If its still running, stop syncing in 10 seconds. */
  if(usersync.isRunning)
    usersync.stop()
}, 10000)

Documentation

localsync(key: string, action: (...args) => payload, handler: payload => {}, [opts: Object]): { start, stop, trigger, isRunning, isFallback }

opts

name type default description
tracing boolean false toggles tracing for debugging purposes
logger Object console the logger object to trace to
loglevel string 'info' the log level to use when tracing (error, warn, info, trace)

IE / Edge fallback props for cookiesync

name type default description
pollFrequency number 3000 the number in milliseconds that should be used for cookie polling
idLength number 8 the number of characters to use for tracking the current instance (tab)
path string '/' The path to use for cookies
secure boolean false Whether to set the secure flag on cookies or not (not recommended)
httpOnly boolean false Whether to set the http only flag on cookies or not