{"id":13816815,"url":"https://github.com/yuanchuan/node-watch","last_synced_at":"2025-05-15T04:05:51.446Z","repository":{"id":3339391,"uuid":"4383680","full_name":"yuanchuan/node-watch","owner":"yuanchuan","description":"A wrapper and enhancements for fs.watch","archived":false,"fork":false,"pushed_at":"2024-02-19T06:50:08.000Z","size":213,"stargazers_count":341,"open_issues_count":6,"forks_count":43,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-14T05:55:01.593Z","etag":null,"topics":["fs-watch","watch-files","watcher","wrapper"],"latest_commit_sha":null,"homepage":"https://npm.im/node-watch","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/yuanchuan.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-05-20T09:33:48.000Z","updated_at":"2025-03-30T00:40:18.000Z","dependencies_parsed_at":"2024-06-18T12:20:21.511Z","dependency_job_id":null,"html_url":"https://github.com/yuanchuan/node-watch","commit_stats":{"total_commits":246,"total_committers":18,"mean_commits":"13.666666666666666","dds":0.4512195121951219,"last_synced_commit":"5743e51a861bfe3d372a99dd388626b324905065"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanchuan%2Fnode-watch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanchuan%2Fnode-watch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanchuan%2Fnode-watch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuanchuan%2Fnode-watch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuanchuan","download_url":"https://codeload.github.com/yuanchuan/node-watch/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270646,"owners_count":22042859,"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":["fs-watch","watch-files","watcher","wrapper"],"created_at":"2024-08-04T06:00:22.102Z","updated_at":"2025-05-15T04:05:46.427Z","avatar_url":"https://github.com/yuanchuan.png","language":"JavaScript","readme":"# node-watch [![Status](https://github.com/yuanchuan/node-watch/actions/workflows/ci.yml/badge.svg)](https://github.com/yuanchuan/node-watch/actions/workflows/ci.yml/badge.svg)\n\nA wrapper and enhancements for [fs.watch](http://nodejs.org/api/fs.html#fs_fs_watch_filename_options_listener).\n\n[![NPM](https://nodei.co/npm/node-watch.png?downloads=true\u0026downloadRank=true\u0026stars=true)](https://nodei.co/npm/node-watch.png/)\n\n\n## Installation\n\n```bash\nnpm install node-watch\n```\n\n## Example\n\n```js\nvar watch = require('node-watch');\n\nwatch('file_or_dir', { recursive: true }, function(evt, name) {\n  console.log('%s changed.', name);\n});\n```\n\nNow it's fast to watch **deep** directories on macOS and Windows, since the `recursive` option is natively supported except on Linux.\n\n```js\n// watch the whole disk\nwatch('/', { recursive: true }, console.log);\n```\n\n\n## Why?\n\n* Some editors will generate temporary files which will cause the callback function to be triggered multiple times.\n* The callback function will only be triggered once on watching a single file.\n* \u003cdel\u003eMissing an option to watch a directory recursively.\u003c/del\u003e\n* Recursive watch is not supported on Linux or in older versions of nodejs.\n* Keep it simple, stupid.\n\n\n## Options\n\nThe usage and options of `node-watch` are compatible with [fs.watch](https://nodejs.org/dist/latest-v7.x/docs/api/fs.html#fs_fs_watch_filename_options_listener).\n* `persistent: Boolean` (default **true**)\n* `recursive: Boolean` (default **false**)\n* `encoding: String` (default **'utf8'**)\n\n**Extra options**\n\n* `filter: RegExp | Function`\n\n   Return that matches the filter expression.\n\n    ```js\n    // filter with regular expression\n    watch('./', { filter: /\\.json$/ });\n\n    // filter with custom function\n    watch('./', { filter: f =\u003e !/node_modules/.test(f) });\n\n    ```\n\n   Each file and directory will be passed to the filter to determine whether\n   it will then be passed to the callback function. Like `Array.filter` does in `JavaScript`.\n   There are three kinds of return values for filter function:\n\n     * **`true`**: Will be passed to callback.\n     * **`false`**: Will not be passed to callback.\n     * **`skip`**: Same with `false`, and skip to watch all its subdirectories.\n\n   On Linux, where the `recursive` option is not natively supported,\n   it is more efficient to skip ignored directories by returning the `skip` flag:\n\n    ```js\n    watch('./', {\n      recursive: true,\n      filter(f, skip) {\n        // skip node_modules\n        if (/\\/node_modules/.test(f)) return skip;\n        // skip .git folder\n        if (/\\.git/.test(f)) return skip;\n        // only watch for js files\n        return /\\.js$/.test(f);\n      }\n    });\n\n    ```\n\n    If you prefer glob patterns you can use [minimatch](https://www.npmjs.com/package/minimatch) or [picomatch](https://www.npmjs.com/package/picomatch)\n    together with filter:\n\n     ```js\n     const pm = require('picomatch');\n     let isMatch = pm('*.js');\n\n     watch('./', {\n       filter: f =\u003e isMatch(f)\n     });\n     ```\n\n* `delay: Number` (in ms, default **200**)\n\n   Delay time of the callback function.\n\n    ```js\n    // log after 5 seconds\n    watch('./', { delay: 5000 }, console.log);\n    ```\n\n## Events\n\nThe events provided by the callback function is either `update` or `remove`, which is less confusing to `fs.watch`'s `rename` or `change`.\n\n```js\nwatch('./', function(evt, name) {\n\n  if (evt == 'update') {\n    // on create or modify\n  }\n\n  if (evt == 'remove') {\n    // on delete\n  }\n\n});\n```\n\n\n## Watcher object\n\nThe watch function returns a [fs.FSWatcher](https://nodejs.org/api/fs.html#fs_class_fs_fswatcher) like object as the same as `fs.watch` (\u003e= v0.4.0).\n\n#### Watcher events\n\n```js\nlet watcher = watch('./', { recursive: true });\n\nwatcher.on('change', function(evt, name) {\n  // callback\n});\n\nwatcher.on('error', function(err) {\n  // handle error\n});\n\nwatcher.on('ready', function() {\n  // the watcher is ready to respond to changes\n});\n```\n\n#### Close\n\n```js\n// close\nwatcher.close();\n\n// is closed?\nwatcher.isClosed()\n```\n\n#### List of methods\n\n* `.on`\n* `.once`\n* `.emit`\n* `.close`\n* `.listeners`\n* `.setMaxListeners`\n* `.getMaxListeners`\n\n##### Extra methods\n* `.isClosed` detect if the watcher is closed\n* `.getWatchedPaths` get all the watched paths\n\n\n## Known issues\n\n**Windows, node \u003c v4.2.5**\n\n  * Failed to detect `remove` event\n  * Failed to get deleted filename or directory name\n\n**MacOS, node 0.10.x**\n  * Will emit double event if the directory name is of one single character.\n\n\n## Misc\n\n#### 1. Watch multiple files or directories in one place\n```js\nwatch(['file1', 'file2'], console.log);\n```\n\n#### 2. Customize watch command line tool\n```js\n#!/usr/bin/env node\n\n// https://github.com/nodejs/node-v0.x-archive/issues/3211\nrequire('epipebomb')();\n\nlet watcher = require('node-watch')(\n  process.argv[2] || './', { recursive: true }, console.log\n);\n\nprocess.on('SIGINT', watcher.close);\n```\nMonitoring chrome from disk:\n```bash\n$ watch / | grep -i chrome\n```\n\n#### 3. Got ENOSPC error?\n\nIf you get ENOSPC error, but you actually have free disk space - it means that your OS watcher limit is too low and you probably want to recursively watch a big tree of files.\n\nFollow this description to increase the limit:\n[https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit](https://confluence.jetbrains.com/display/IDEADEV/Inotify+Watches+Limit)\n\n\n## Alternatives\n\n* [chokidar](https://github.com/paulmillr/chokidar)\n* [gaze](https://github.com/shama/gaze)\n* [mikeal/watch](https://github.com/mikeal/watch)\n\n## Contributors\n\nThanks goes to [all wonderful people](https://github.com/yuanchuan/node-watch/graphs/contributors) who have helped this project.\n\n## License\nMIT\n\nCopyright (c) 2012-2021 [yuanchuan](https://github.com/yuanchuan)\n","funding_links":[],"categories":["Packages"],"sub_categories":["Others"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuanchuan%2Fnode-watch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuanchuan%2Fnode-watch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuanchuan%2Fnode-watch/lists"}