Chokidar: надёжный сторож для ваших файлов

Когда в последний раз вы сталкивались с тем, что ваш файловый вотчер пропускал изменения или срабатывал по два раза? А может, вы до сих пор используете костыли с fs.watchFile и регулярными проверками? Пора познакомиться с Chokidar — проверенной временем библиотекой, которая решает эти проблемы раз и навсегда.

Что такое Chokidar?

Chokidar — это минималистичная кроссплатформенная библиотека для отслеживания изменений файлов в Node.js. Созданная ещё в 2012 году для фреймворка Brunch, она прошла долгий путь развития и теперь используется в более чем 30 миллионах репозиториев.

Главное преимущество Chokidar перед нативными методами Node.js — стабильность и предсказуемость работы. В то время как fs.watch может вести себя по-разному на разных платформах и пропускать события, Chokidar обеспечивает единообразное поведение везде.

Почему стоит выбрать Chokidar?

Вот несколько веских причин:

Корректная обработка событий
- На macOS правильно определяются имена файлов
- События не дублируются
- Чёткое разделение на add/change/unlink вместо невнятного 'rename'
Поддержка сложных сценариев
- Атомарные записи (через временные файлы)
- Постепенная запись больших файлов (с возможностью дождаться завершения)
- Фильтрация по файлам и директориям
Гибкость настройки
- Поддержка символических ссылок
- Контроль глубины рекурсивного отслеживания
- Возможность использования как polling, так и native watch API

Как это работает?

Chokidar использует нативный модуль fs Node.js, но добавляет над ним слой абстракции, который:

Нормализует события между разными платформами
Проверяет изменения через fs.stat при необходимости
Предоставляет единый API для всех ОС

Под капотом библиотека в основном полагается на fs.watch, что минимизирует нагрузку на CPU. Однако для особых случаев (например, при работе с сетевыми файловыми системами) можно включить режим polling.

import chokidar from 'chokidar';

// Простейший пример
chokidar.watch('.').on('all', (event, path) => {
  console.log(`${event}: ${path}`);
});

Практическое применение

Chokidar идеально подходит для:

Систем сборки (вроде webpack или vite)
Dev-серверов с hot reload
Инструментов для разработчиков
Скриптов для синхронизации файлов
Мониторинга логов в реальном времени

Вот более сложный пример с фильтрацией только JavaScript-файлов:

const watcher = chokidar.watch('.', {
  ignored: (path, stats) => stats?.isFile() && !path.endsWith('.js'),
  persistent: true
});

watcher
  .on('add', path => console.log(`Добавлен файл: ${path}`))
  .on('change', path => console.log(`Изменён файл: ${path}`))
  .on('unlink', path => console.log(`Удалён файл: ${path}`));

Советы по использованию

Ресурсы системы Chokidar рекурсивно отслеживает все поддиректории, поэтому не стоит указывать слишком широкие пути. Если вам нужно следить за всей файловой системой, лучше явно указать нужные директории.
Атомарные записи Многие редакторы (например, Vim) используют временные файлы при сохранении. Параметр atomic: true позволяет корректно обрабатывать такие случаи.
Большие файлы Для файлов, которые записываются постепенно, используйте awaitWriteFinish, чтобы событие срабатывало только по завершению записи.

Что нового в версии 4?

Сентябрь 2024 года принёс нам Chokidar v4 с важными изменениями:

Уменьшение зависимостей с 13 до 1
Удаление поддержки glob-шаблонов (но их можно эмулировать)
Поддержка ES Modules и CommonJS
Минимальная версия Node.js повышена до v14

Chokidar — это проверенное решение для файлового мониторинга, которое избавит вас от головной боли с нативными API Node.js. Если ваш проект так или иначе работает с файловой системой, стоит попробовать эту библиотеку.

Особенно она пригодится:

Разработчикам инструментов для работы с файлами
Создателям систем сборки
Автоматизаторам рутинных задач

Установить Chokidar можно через npm:

npm install chokidar

А что вы используете для отслеживания файловых изменений? Делитесь опытом в комментариях!