devwatch

README

devwatch

fsnotify implementation Watches file system changes in a project directory, triggering custom handlers for file and folder events, and supporting browser reloads and selective file ignoring.

Public API

Main Types

// FilesEventHandlers unifies asset and Go file event handling.
// It allows handlers to specify which file extensions they support and how to process them.
type FilesEventHandlers interface {
	MainInputFileRelativePath() string // eg: go => "app/server/main.go" | js =>"app/pwa/public/main.js"
	// NewFileEvent handles file events (create, remove, write, rename).
	NewFileEvent(fileName, extension, filePath, event string) error
	SupportedExtensions() []string // eg: [".go"], [".js",".css"], etc.
	UnobservedFiles() []string     // eg: main.exe, main.js
}

// Folder event handler interface
// event: create, remove, write, rename
 type FolderEvent interface {
     NewFolderEvent(folderName, path, event string) error
 }

// Main configuration struct
 type WatchConfig struct {
     AppRootDir         string               // Project root directory
     FilesEventHandlers []FilesEventHandlers // All file event handlers are managed here
     FolderEvents       FolderEvent          // Handler for folder events
     BrowserReload      func() error         // Function to reload the browser
     Logger             func(message ...any) // Log output
     ExitChan           chan bool            // Channel to signal exit
     UnobservedFiles    func() []string      // Files/folders to ignore (e.g. .git, .vscode)
 }

 type DevWatch struct {
     *WatchConfig
     // ... (internal fields)
 }

Initialization and Usage

// Create your handlers that implement the FilesEventHandlers interface
// Example handlers:
// assetsHandler handles .css, .js, .html
// goServerHandler handles .go files for the server
// tinyWasmHandler handles .go files for wasm and .js for runtime detection

// Create configuration
cfg := &devwatch.WatchConfig{
    AppRootDir:      "/path/to/your/app",
    FilesEventHandlers: []devwatch.FilesEventHandlers{
        assetsHandler,
        goServerHandler,
        tinyWasmHandler,
    },
    FolderEvents:    yourFolderHandler,
    BrowserReload:   yourReloadFunc,
    Logger:          func(message ...any) { fmt.Println(message...) },
    ExitChan:        make(chan bool),
    UnobservedFiles: func() []string { return []string{".git", ".vscode"} },
}

// Create watcher
watcher := devwatch.New(cfg)

// Start the watcher (example with WaitGroup)
var wg sync.WaitGroup
wg.Add(1)
go watcher.FileWatcherStart(&wg)

Notes

• Implement your own handlers for FilesEventHandlers and FolderEvent according to your application logic.
• Each handler in FilesEventHandlers must specify the file extensions it supports via the SupportedExtensions() method.
• For .go files, the system automatically identifies the correct handler(s) using godepfind dependency logic.
• The handlers are processed in the order they are registered in the FilesEventHandlers slice.
• Use the ExitChan channel to stop the watcher gracefully.

Contributing

Documentation

Index

• func GetFileName(path string) (string, error)
• type DevWatch
  • func New(c *WatchConfig) *DevWatch
  • func (h *DevWatch) AddDirectoryToWatcher(path string) error
  • func (h *DevWatch) AddFilesEventHandlers(handlers ...FilesEventHandlers)
  • func (h *DevWatch) Contain(path string) bool
  • func (h *DevWatch) FileWatcherStart(wg *sync.WaitGroup)
  • func (h *DevWatch) InitialRegistration()
  • func (dw *DevWatch) Logger(messages ...any)
  • func (dw *DevWatch) Name() string
  • func (h *DevWatch) RemoveDirectoryFromWatcher(path string) error
  • func (dw *DevWatch) SetLog(f func(message ...any))
  • func (dw *DevWatch) SetShouldWatch(f func() bool)
  • func (dw *DevWatch) SetWatcher(w *fsnotify.Watcher)
  • func (dw *DevWatch) Watcher() *fsnotify.Watcher
• type FilesEventHandlers
• type FolderEvent
• type WatchConfig

Functions

func GetFileName

func GetFileName(path string) (string, error)

GetFileName returns the filename from a path Example: "theme/index.html" -> "index.html"

Types

type DevWatch

type DevWatch struct {
	*WatchConfig
	// contains filtered or unexported fields
}

func New

func New(c *WatchConfig) *DevWatch

func (*DevWatch) AddDirectoryToWatcher

func (h *DevWatch) AddDirectoryToWatcher(path string) error

AddDirectoryToWatcher adds a directory and its subdirectories to the watcher.

func (*DevWatch) AddFilesEventHandlers

func (h *DevWatch) AddFilesEventHandlers(handlers ...FilesEventHandlers)

AddHandlers allows adding handlers dynamically after DevWatch initialization. This is useful when handlers are created after the watcher starts (e.g., deploy handlers). The method extracts UnobservedFiles from each handler and adds them to the no_add_to_watch map.

func (*DevWatch) Contain

func (h *DevWatch) Contain(path string) bool

func (*DevWatch) FileWatcherStart

func (h *DevWatch) FileWatcherStart(wg *sync.WaitGroup)

func (*DevWatch) InitialRegistration

func (h *DevWatch) InitialRegistration()

func (*DevWatch) Logger

func (dw *DevWatch) Logger(messages ...any)

func (*DevWatch) Name

func (dw *DevWatch) Name() string

func (*DevWatch) RemoveDirectoryFromWatcher

func (h *DevWatch) RemoveDirectoryFromWatcher(path string) error

RemoveDirectoryFromWatcher removes a directory and its subdirectories from the watcher.

func (*DevWatch) SetLog

func (dw *DevWatch) SetLog(f func(message ...any))

func (*DevWatch) SetShouldWatch

func (dw *DevWatch) SetShouldWatch(f func() bool)

SetShouldWatch sets a function that determines if the file watcher should start.

func (*DevWatch) SetWatcher

func (dw *DevWatch) SetWatcher(w *fsnotify.Watcher)

SetWatcher sets the fsnotify.Watcher in a thread-safe way.

func (*DevWatch) Watcher

func (dw *DevWatch) Watcher() *fsnotify.Watcher

Watcher returns the current fsnotify.Watcher in a thread-safe way.

type FilesEventHandlers

type FilesEventHandlers interface {
	MainInputFileRelativePath() string // eg: go => "app/server/main.go" | js =>"app/pwa/public/main.js"
	// NewFileEvent handles file events (create, remove, write, rename).
	NewFileEvent(fileName, extension, filePath, event string) error
	SupportedExtensions() []string // eg: [".go"], [".js",".css"], etc.
	UnobservedFiles() []string     // eg: main.exe, main.js
}

FilesEventHandlers unifies asset and Go file event handling. It allows handlers to specify which file extensions they support and how to process them.

type FolderEvent

type FolderEvent interface {
	NewFolderEvent(folderName, path, event string) error
}

event: create, remove, write, rename

type WatchConfig

type WatchConfig struct {
	AppRootDir         string               // eg: "home/user/myNewApp"
	FilesEventHandlers []FilesEventHandlers // All file event handlers are managed here
	FolderEvents       FolderEvent          // when directories are created/removed for architecture detection

	BrowserReload func() error // when change frontend files reload browser

	ExitChan        chan bool       // global channel to signal the exit
	UnobservedFiles func() []string // files that are not observed by the watcher eg: ".git", ".gitignore", ".vscode",  "examples",
}