mini-sync

mini-sync is an incredibly tiny, live-reloading development server that uses server-sent events to keep your browser in sync with your front-end code.

Key features

• 🦗 For less than a few hundred KBs, get a fully functional static server that can communicate with browsers during development
• ♻️ Bundles the maintained version of livereload-js in the client code to manage the reloading logic
• 📦 Client code may be included in browsers via your preferred bundler, the static server or CDN

Table of contents

• Setup
• Usage
  • Server
  • Client
    • Load directly in your HTML
    • Conditionally add it to your bundle
• API
  • Table of Contents
  • CreateReturn
    • Properties
  • StartReturn
    • Properties
  • create
    • Parameters
    • Examples
  • reload
    • Parameters
  • close
  • start
• Possible future features
• License

Setup

mini-sync has two layers - the server code that's responsible for serving static assets and delivering reload requests, and the client code that needs to be present on your page to receive messages from the server.

Install the package with npm, yarn, or pnpm:

npm install --save-dev mini-sync
# or
yarn add --dev mini-sync
# or
pnpm add --save-dev mini-sync

Usage

You will need to integrate mini-sync both into your build pipeline and your JavaScript/HTML.

Server

Implement mini-sync in your build tool by using it as the static server for your assets during development. Once the server is created, it will return a reload function that can be called any time you need to communicate with the browser, a start function for activating the static server and watching for reload calls, and a close function for stopping the server.

constchokidar=require('chokidar');// or your preferred file watcherconst{ create }=require('mini-sync');constdirToWatch='./app';asyncfunctionmain(){constserver=create({dir: dirToWatch,port: 3000,});constwatcher=chokidar.watch('.',{cwd: dirToWatch});// every time a file changes, we call the reload commandwatcher.on('change',(path)=>{server.reload(path);});// start our dev serverconst{ local, network }=awaitserver.start();// report out what our URLs areconsole.log(`Local server URL: ${local}`);// http://localhost:3000console.log(`Local network URL: ${network}`);// http://127.x.x.x:3000// ...some time laterawaitserver.close();}main().catch(console.error);

Client

mini-sync has a tiny script that needs to be added to your JavaScript bundles or loaded on your HTML page. How best to go about this will depend on your environment, but there are a few methods to consider.

Load directly in your HTML

If you just want to get the code in your page with minimal fuss, you can add it directly to your HTML. Ideally it would run before the rest of your JavaScript does.

As of 0.2.0 the mini-sync server hosts its own copy of the client script, and it can be referenced in your HTML.

<scriptasyncsrc="/__mini_sync__/client.js"></script>

It's also possible to load it via unpkg.com.

<scriptasyncsrc="https://unpkg.com/mini-sync"></script>

Conditionally add it to your bundle

Most bundlers support conditional includes based on the value of the NODE_ENV environment variable, or a similar mechanism. If you can do this in the configuration itself, that's great! But you also could include it directly in your JavaScript itself within an if statement.

if(process.env.NODE_ENV==='development'){require('mini-sync/client');}

In this case it will be present in development builds, but in production builds it will be skipped or entirely removed by your minifier.

API

Table of Contents

• CreateReturn
  • Properties
• StartReturn
  • Properties
• create
  • Parameters
  • Examples
• reload
  • Parameters
• close
• start

CreateReturn

What's returned when the create function is called.

Type: object

Properties

• closeFunction Stops the server if it is running
• reloadFunction When called this function will reload any connected HTML documents, can accept the path to a file to target for reload
• startFunction When called the server will begin running

StartReturn

What's returned by the start function in a Promise.

Type: object

Properties

• localstring The localhost URL for the static site
• networkstring The local networked URL for the static site
• portnumber The port the server ended up on

create

Creates a server on the preferred port and begins serving the provided directories locally.

Parameters

• optionsobject (optional, default {})
  • options.dir(string | Array<string>)? The directory or list of directories to serve (optional, default process.cwd())
  • options.portnumber? The port to serve on (optional, default 3000)

Examples

const{ create }=require('mini-sync');constserver=create({dir: 'app',port: 3000});const{ local }=awaitserver.start();console.log(`Now serving at: ${local}`);// any time a file needs to change, use "reload"server.reload('app.css');// reloads the whole pageserver.reload();// close the serverawaitserver.close();

Returns CreateReturn

reload

Tells all connected clients to reload.

Parameters

• filestring? The file to reload

close

Returns a promise once the server closes.

Returns Promise<void>

start

Returns a promise once the server starts.

Returns Promise<StartReturn>

Possible future features

• Automatic injection of the client code into served HTML pages
• The ability to additionally proxy existing servers

License

MIT