Logux Client

Logux is a client-server communication protocol. It synchronizes events between clients and server logs.

This 6 KB library allows you to put events (which look similar to Redux “actions”) to a local log and synchronize them with Logux server and thus with every other client being online.

This is a low-level client API. Redux-like API, which is supposed to be more suitable for most of developers, is coming soon.

Getting Started

Add Logux to your Project

This project uses npm package manager. So you will need Webpack or Browserify to build a JS bundle for browsers.

Install Logux Client:

npm install --save logux-client

Add Credentials to the Client

You should use a secret token for authentication at the Logux server.

We suggest adding a special token column to the users table of your application and filling it with auto-generated random strings.

When the user requests index.html from your app, HTTP server would add <meta> tags with a token and Logux server URL.

<meta name="token" content="<%= user.token %>" />
<meta name="server" content="wss://example.com:1337" />

However, it is not the only possible way for communication. You could also use cookies or tools like Gon.

Create Logux Client

Create Logux Client instance in your client-side JS; onready event handler seems to be a good place for this:

var Client = require('logux-client/client')

var server = document.querySelector('meta[name=server]')
var token = document.querySelector('meta[name=token]')

var logux = new Client({
  credentials: token.content,
  subprotocol: '1.0.0',
  url: server.content
})
logux.sync.connection.connect()

Process Events

Add callbacks for new events coming to the client log (from server, other clients or local logux.log.add call):

logux.log.on('event', function (event, meta) {
  if (event.type === 'changeName') {
    var user = document.querySelector('.user[data-id=' + event.user + ']')
    if (user) {
      document.querySelector(' .user__name').innerText = event.name
    }
  }
})

Read logux-core docs for logux.log API.

Emit Events

When you need to send information to server, just add an event to log:

submit.addEventListener('click', function () {
  logux.log.add({
    type: 'changeName',
    user: userId.value,
    name: name.value
  })
}, false)

Show Connection State

Notify user if connection was lost:

var favicon = document.querySelector('link[rel~="icon"]')
var notice  = document.querySelector('.offline-notice')

logux.sync.on('state', function () {
  if (logux.sync.connected) {
    favicon.href = '/favicon.ico'
    notice.classList.add('.offline-notice_hidden')
  } else {
    favicon.href = '/offline.ico'
    notice.classList.remove('.offline-notice_hidden')
  }
})

Notify user on page leaving, if some data is not synchronized yet:

window.onbeforeunload = function (e) {
  if (logux.sync.state === 'wait') {
    e.returnValue = 'Edits were not saved'
    return e.returnValue
  }
}