mini-sync
v0.3.0
Published
A tiny, live reloading development server for static sites.
Downloads
132
Readme
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
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.
const chokidar = require('chokidar'); // or your preferred file watcher
const { create } = require('mini-sync');
const dirToWatch = './app';
async function main() {
const server = create({
dir: dirToWatch,
port: 3000,
});
const watcher = chokidar.watch('.', { cwd: dirToWatch });
// every time a file changes, we call the reload command
watcher.on('change', (path) => {
server.reload(path);
});
// start our dev server
const { local, network } = await server.start();
// report out what our URLs are
console.log(`Local server URL: ${local}`); // http://localhost:3000
console.log(`Local network URL: ${network}`); // http://127.x.x.x:3000
// ...some time later
await server.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.
<script async src="/__mini_sync__/client.js"></script>
It's also possible to load it via unpkg.com.
<script async src="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
What's returned when the create
function is called.
Type: object
Properties
close
Function Stops the server if it is runningreload
Function When called this function will reload any connected HTML documents, can accept the path to a file to target for reloadstart
Function When called the server will begin running
StartReturn
What's returned by the start
function in a Promise.
Type: object
Properties
local
string The localhost URL for the static sitenetwork
string The local networked URL for the static siteport
number The port the server ended up on
create
Creates a server on the preferred port and begins serving the provided directories locally.
Parameters
options
object (optional, default{}
)
Examples
const { create } = require('mini-sync');
const server = create({ dir: 'app', port: 3000 });
const { local } = await server.start();
console.log(`Now serving at: ${local}`);
// any time a file needs to change, use "reload"
server.reload('app.css');
// reloads the whole page
server.reload();
// close the server
await server.close();
Returns CreateReturn
reload
Tells all connected clients to reload.
Parameters
file
string? 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