{"id":15701090,"url":"https://github.com/ahmadnassri/node-serve-reload-replace","last_synced_at":"2025-04-30T22:25:30.643Z","repository":{"id":37086649,"uuid":"309154054","full_name":"ahmadnassri/node-serve-reload-replace","owner":"ahmadnassri","description":"simple http server with built-in live reload, server-sent events, server side includes, and more!","archived":false,"fork":false,"pushed_at":"2025-01-07T20:54:02.000Z","size":516,"stargazers_count":6,"open_issues_count":5,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-14T05:32:13.982Z","etag":null,"topics":["eventsource","node","reload","server","sse","ssi","static","watch"],"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/ahmadnassri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ahmadnassri"]}},"created_at":"2020-11-01T17:49:35.000Z","updated_at":"2025-01-07T20:54:06.000Z","dependencies_parsed_at":"2024-06-17T22:03:37.222Z","dependency_job_id":"775d3af3-5963-43fa-9a34-b431b123a717","html_url":"https://github.com/ahmadnassri/node-serve-reload-replace","commit_stats":{"total_commits":266,"total_committers":2,"mean_commits":133.0,"dds":0.1578947368421053,"last_synced_commit":"3c551e2ab3036ca6101ac89799557500432dda7a"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":"ahmadnassri/template-node-lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmadnassri%2Fnode-serve-reload-replace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmadnassri%2Fnode-serve-reload-replace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmadnassri%2Fnode-serve-reload-replace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmadnassri%2Fnode-serve-reload-replace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahmadnassri","download_url":"https://codeload.github.com/ahmadnassri/node-serve-reload-replace/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246379366,"owners_count":20767694,"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":["eventsource","node","reload","server","sse","ssi","static","watch"],"created_at":"2024-10-03T19:59:30.456Z","updated_at":"2025-03-31T17:31:26.531Z","avatar_url":"https://github.com/ahmadnassri.png","language":"JavaScript","funding_links":["https://github.com/sponsors/ahmadnassri"],"categories":[],"sub_categories":[],"readme":"# SRR: Serve Reload Replace\n\nsimple http server with built-in live reload, server-sent events, server side includes, and more!\n\n[![license][license-img]][license-url]\n[![release][release-img]][release-url]\n[![semantic][semantic-img]][semantic-url]\n\n## Features\n\n- **Serve**: Simple HTTP Server for static files\n  - forced cache busting through `Cache-Control: no-store` headers\n- **Reload**: Automatically watches for file changes, and reloads pages\n  - uses light weight [Server Sent Events][] to notify browser with file changes\n  - automatically injects watcher client\n  - customize the client behavior with your own client script\n- **Replace**: Supports [Server Side Includes][] directives\n\n## Install\n\n``` bash\n$ npm install --global serve-reload-replace\n```\n\n## Usage\n\n``` bash\n$ srr --help\n\nUsage: srr [options]\n  --root     Path to serve \u0026 watch                                 default: $PWD\n  --client   Path to custom EventSource client                     default: built-in\n  --address  Specify network interface to use                      default: 0.0.0.0\n  --port     Specify a port to use                                 default: 8080\n  --index    Specify which file should be used as the index page   default: index.html\n  --verbose  Verbose logging                                       default: false\n  --help     Display Help\n```\n\n###### quick start\n\n``` bash\n$ cd ~/project\n$ srr\n\n[02:02:46 PM] • Listening on 0.0.0.0 8080\n[02:02:47 PM] • Watching files in /home/ahmad/project/\n```\n\nThis will launch the server in the current working director and start watching local files for changes.\n\nopen a browser window and navigate to `http://localhost:8080/` to start browsing.\n\nThe built-in EventSource client will automatically reload all pages whenever any file changes\n\n\u003e ***NOTE**: Future plans include selectively reloading resources in the browser.*\n\n###### with optional arguments \u0026 custom client\n\n``` bash\n$ srr --root=~/projects/website/ --address=127.0.0.1 --port=2000 --client=js/my-client.js\n\n[02:02:46 PM] • Listening on 127.0.0.1 2000\n[02:02:47 PM] • Watching files in /home/ahmad/projects/website/\n```\n\ncreate a new file named `my-client.js` under `~/projects/website/js/`\n\n``` js\n// connect to Server Sent Events special route\nconst sse = new EventSource(`${window.location.origin}/__events`);\n\nsse.addEventListener(\"unlink\", console.log);\nsse.addEventListener(\"add\", console.log);\nsse.addEventListener(\"change\", console.log);\nsse.addEventListener(\"error\", (event) =\u003e console.error(\"SSE error\"));\n```\n\n\u003e ***NOTE**: see [Server Sent Events][1] for more details.*\n\nopen a browser window and navigate to `http://127.0.0.1:2000/`\n\n``` bash\n[02:05:25 PM] • GET / ↦  200 OK\n[02:05:25 PM] • SSE Client Connected: 1604257525819\n```\n\nwith the server running, and your browser connected, edit / update / delete any file under your project folder and your client JS will receive events, while the server logs will show the events and the file path:\n\n``` bash\n[02:10:15 PM] • change index.html\n[02:11:30 PM] • add foo.html\n[02:11:42 PM] • unlink foo.html\n```\n\n![][2]\n\n## Server Sent Events\n\nFile system events are forwarded from [`Chokidar`][] using [Server Sent Events][].\n\nThe built-in client is automatically served from the `/__client` endpoint, and it connects to the special path `/__events` which serves the events.\n\nThe built-in client simply listens to `all` event and executes a page reload through `window.location.reload()`\n\n\u003e **TODO:**\n\u003e\n\u003e - Track actively opened files, and only notify relevant client sessions\n\u003e - Investigate using `window.performance.getEntriesByType('resource')` API to target specific elements per page / session (e.g. images / css)\n\n### Writing a custom SSE client\n\nWhile the default behavior of the built-in client focuses on reloading the page content, you can replace it with your own client logic, simply point to the client path using `--client` argument.\n\n\u003e ***Note**: `--client` must be relative path to `--root`*\n\n###### client code\n\n``` js\nconst sse = new EventSource(`${window.location.origin}/__events`);\n\nsse.addEventListener(\"all\", console.log);\n```\n\n\u003e *See [`Using server-sent events`][] article by Mozilla for more examples on what you can do.*\n\n### Available events\n\n`add`, `addDir`, `change`, `unlink`, `unlinkDir`, `all`\n\n\u003e ***Note**: for more details check out [Chokidar's docs][]*\n\n## Server Side Includes\n\nThe server will automatically process [SSI][Server Side Includes] directives:\n\n### Supported Directives\n\n| directive  | parameters     | example                              | description                                              |\n|------------|----------------|--------------------------------------|----------------------------------------------------------|\n| `echo`     | `var`          | `\u003c!--#echo var=\"NODE_ENV\" --\u003e`       | displays the value of the specified environment variable |\n| `set`      | `var`, `value` | `\u003c!--#set var=\"foo\" value=\"bar\" --\u003e` | sets the value of an environment variable                |\n| `printenv` | [`space`][]    | `\u003c!--#printenv space=\"  \" --\u003e`       | outputs a list of all environment variables as JSON      |\n\n## API\n\nYou can use the `serve-reload-replace` programmatically as well:\n\n``` js\nconst SRR = require('serve-reload-replace')\n\nconst instance = new SRR({\n  verbose = false,\n  root = process.cwd(),\n  index = 'index.html',\n  client\n})\n\ninstance.start({\n  address: '0.0.0.0',\n  port: 8080\n})\n\ninstance.stop()\n```\n\n*See [CLI Usage][] for available options.*\n\n## Docker\n\nRun as a docker image:\n\n``` bash\n$ docker run -it -p 8080:8080 -v $(pwd)/www:/www ahmadnassri/serve-reload-replace\n```\n\n###### pass arguments and match the port and volume mount\n\n``` bash\n$ docker run -it -p 3000:3000 -v /path/to/your/project:/my-project ahmadnassri/serve-reload-replace --port=3000 --root=/my-project\n```\n\n  [Server Sent Events]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events\n  [Server Side Includes]: https://en.wikipedia.org/wiki/Server_Side_Includes\n  [1]: #server-sent-events\n  [2]: docs/browser-console.png\n  [`Chokidar`]: https://github.com/paulmillr/chokidar\n  [`Using server-sent events`]: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events\n  [Chokidar's docs]: https://github.com/paulmillr/chokidar#methods--events\n  [`space`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify\n  [CLI Usage]: #usage\n\n----\n\u003e Author: [Ahmad Nassri](https://www.ahmadnassri.com/) \u0026bull;\n\u003e Twitter: [@AhmadNassri](https://twitter.com/AhmadNassri)\n\n[license-url]: LICENSE\n[license-img]: https://badgen.net/github/license/ahmadnassri/node-serve-reload-replace\n\n[release-url]: https://github.com/ahmadnassri/node-serve-reload-replace/releases\n[release-img]: https://badgen.net/github/release/ahmadnassri/node-serve-reload-replace\n\n[semantic-url]: https://github.com/ahmadnassri/node-serve-reload-replace/actions?query=workflow%3Arelease\n[semantic-img]: https://badgen.net/badge/📦/semantically%20released/blue\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmadnassri%2Fnode-serve-reload-replace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahmadnassri%2Fnode-serve-reload-replace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmadnassri%2Fnode-serve-reload-replace/lists"}