{"id":18735657,"url":"https://github.com/rdmurphy/mini-sync","last_synced_at":"2025-04-12T19:21:05.461Z","repository":{"id":37082575,"uuid":"219356898","full_name":"rdmurphy/mini-sync","owner":"rdmurphy","description":"🦗 An incredibly tiny, live-reloading development server that keeps your browser in sync with your front-end code.","archived":false,"fork":false,"pushed_at":"2023-02-03T07:14:22.000Z","size":4198,"stargazers_count":6,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T13:38:19.294Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rdmurphy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-03T19:53:29.000Z","updated_at":"2023-09-28T13:08:56.000Z","dependencies_parsed_at":"2023-02-06T12:01:28.528Z","dependency_job_id":null,"html_url":"https://github.com/rdmurphy/mini-sync","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fmini-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fmini-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fmini-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fmini-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rdmurphy","download_url":"https://codeload.github.com/rdmurphy/mini-sync/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618618,"owners_count":21134271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T15:17:39.864Z","updated_at":"2025-04-12T19:21:05.431Z","avatar_url":"https://github.com/rdmurphy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  mini-sync\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.org/package/mini-sync\"\u003e\u003cimg src=\"https://badgen.net/npm/v/mini-sync\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/rdmurphy/mini-sync/actions?query=workflow%3A%22Node.js+CI%22\"\u003e\u003cimg src=\"https://badgen.net/github/checks/rdmurphy/mini-sync?label=build\" alt=\"build status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://unpkg.com/mini-sync/client/dist/client.js\"\u003e\u003cimg src=\"https://badgen.net/badgesize/gzip/https://unpkg.com/mini-sync/client/dist/client.js\" alt=\"gzip size\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://unpkg.com/mini-sync/client/dist/client.js\"\u003e\u003cimg src=\"https://badgen.net/badgesize/brotli/https://unpkg.com/mini-sync/client/dist/client.js\" alt=\"brotli size\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://packagephobia.now.sh/result?p=mini-sync\"\u003e\u003cimg src=\"https://badgen.net/packagephobia/install/mini-sync\" alt=\"install size\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n`mini-sync` is an incredibly tiny, live-reloading development server that uses [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) to keep your browser in sync with your front-end code.\n\n## Key features\n\n- 🦗 For less **than a few hundred KBs**, get a fully functional static server that can communicate with browsers during development\n- ♻️ Bundles the maintained version of [`livereload-js`](https://github.com/livereload/livereload-js) in the client code to manage the reloading logic\n- 📦 Client code may be included in browsers via your preferred bundler, the static server or CDN\n\n## Table of contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Setup](#setup)\n- [Usage](#usage)\n  - [Server](#server)\n  - [Client](#client)\n    - [Load directly in your HTML](#load-directly-in-your-html)\n    - [Conditionally add it to your bundle](#conditionally-add-it-to-your-bundle)\n- [API](#api)\n  - [Table of Contents](#table-of-contents)\n  - [CreateReturn](#createreturn)\n    - [Properties](#properties)\n  - [StartReturn](#startreturn)\n    - [Properties](#properties-1)\n  - [create](#create)\n    - [Parameters](#parameters)\n    - [Examples](#examples)\n  - [reload](#reload)\n    - [Parameters](#parameters-1)\n  - [close](#close)\n  - [start](#start)\n- [Possible future features](#possible-future-features)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Setup\n\n`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.\n\nInstall the package with `npm`, `yarn`, or `pnpm`:\n\n```sh\nnpm install --save-dev mini-sync\n# or\nyarn add --dev mini-sync\n# or\npnpm add --save-dev mini-sync\n```\n\n## Usage\n\nYou will need to integrate `mini-sync` both into your build pipeline and your JavaScript/HTML.\n\n### Server\n\nImplement `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.\n\n```js\nconst chokidar = require('chokidar'); // or your preferred file watcher\nconst { create } = require('mini-sync');\n\nconst dirToWatch = './app';\n\nasync function main() {\n  const server = create({\n    dir: dirToWatch,\n    port: 3000,\n  });\n\n  const watcher = chokidar.watch('.', { cwd: dirToWatch });\n\n  // every time a file changes, we call the reload command\n  watcher.on('change', (path) =\u003e {\n    server.reload(path);\n  });\n\n  // start our dev server\n  const { local, network } = await server.start();\n\n  // report out what our URLs are\n  console.log(`Local server URL: ${local}`); // http://localhost:3000\n  console.log(`Local network URL: ${network}`); // http://127.x.x.x:3000\n\n  // ...some time later\n  await server.close();\n}\n\nmain().catch(console.error);\n```\n\n### Client\n\n`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.\n\n#### Load directly in your HTML\n\nIf 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.\n\nAs of 0.2.0 the `mini-sync` server hosts its own copy of the client script, and it can be referenced in your HTML.\n\n```html\n\u003cscript async src=\"/__mini_sync__/client.js\"\u003e\u003c/script\u003e\n```\n\nIt's also possible to load it via [unpkg.com](https://unpkg.com/).\n\n```html\n\u003cscript async src=\"https://unpkg.com/mini-sync\"\u003e\u003c/script\u003e\n```\n\n#### Conditionally add it to your bundle\n\nMost 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.\n\n```js\nif (process.env.NODE_ENV === 'development') {\n  require('mini-sync/client');\n}\n```\n\nIn this case it will be present in development builds, but in production builds it will be skipped or entirely removed by your minifier.\n\n## API\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n#### Table of Contents\n\n- [CreateReturn](#createreturn)\n  - [Properties](#properties)\n- [StartReturn](#startreturn)\n  - [Properties](#properties-1)\n- [create](#create)\n  - [Parameters](#parameters)\n  - [Examples](#examples)\n- [reload](#reload)\n  - [Parameters](#parameters-1)\n- [close](#close)\n- [start](#start)\n\n### CreateReturn\n\nWhat's returned when the `create` function is called.\n\nType: [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)\n\n#### Properties\n\n- `close` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Stops the server if it is running\n- `reload` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** When called this function will reload any connected HTML documents, can accept the path to a file to target for reload\n- `start` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** When called the server will begin running\n\n### StartReturn\n\nWhat's returned by the `start` function in a Promise.\n\nType: [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)\n\n#### Properties\n\n- `local` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The localhost URL for the static site\n- `network` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The local networked URL for the static site\n- `port` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** The port the server ended up on\n\n### create\n\nCreates a server on the preferred port and begins serving the provided\ndirectories locally.\n\n#### Parameters\n\n- `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** (optional, default `{}`)\n  - `options.dir` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \\| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\u0026lt;[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\u003e)?** The directory or list of directories to serve (optional, default `process.cwd()`)\n  - `options.port` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The port to serve on (optional, default `3000`)\n\n#### Examples\n\n```javascript\nconst { create } = require('mini-sync');\n\nconst server = create({ dir: 'app', port: 3000 });\n\nconst { local } = await server.start();\n\nconsole.log(`Now serving at: ${local}`);\n\n// any time a file needs to change, use \"reload\"\nserver.reload('app.css');\n\n// reloads the whole page\nserver.reload();\n\n// close the server\nawait server.close();\n```\n\nReturns **[CreateReturn](#createreturn)**\n\n### reload\n\nTells all connected clients to reload.\n\n#### Parameters\n\n- `file` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** The file to reload\n\n### close\n\nReturns a promise once the server closes.\n\nReturns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\u0026lt;void\u003e**\n\n### start\n\nReturns a promise once the server starts.\n\nReturns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\u0026lt;[StartReturn](#startreturn)\u003e**\n\n## Possible future features\n\n- Automatic injection of the client code into served HTML pages\n- The ability to additionally proxy existing servers\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frdmurphy%2Fmini-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frdmurphy%2Fmini-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frdmurphy%2Fmini-sync/lists"}