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) Contain(path string) bool
  • func (h *DevWatch) FileWatcherStart(wg *sync.WaitGroup)
  • func (h *DevWatch) InitialRegistration()
• 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) 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()

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

	Logger          func(message ...any) // For logging output
	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",
}