Eleventy Serve Not Watching Changes? A Diagnostic Guide for Stale Builds

Stale Builds During Eleventy Serve

The most common frustration with Eleventy (`11ty`) is starting the development server with eleventy --serve, seeing a successful initial build, but finding that subsequent edits to templates, data files, or includes do not trigger a rebuild or a browser refresh. The immediate takeaway is that Eleventy's file watching is often constrained by configuration or file exclusion rules, not a fundamental failure of the tool.

Watch Target and Exclusion Checks

Before assuming a bug, verify what Eleventy is actually watching. By default, it monitors the configured input directory, but custom data or layout files outside this scope require explicit registration. Furthermore, exclusion files can silently suppress necessary rebuilds.

Ordered Diagnostic Steps

1. Verify Watch Scope: If you use data files (e.g., in a _data folder) outside the primary input directory, ensure you registered it: eleventyConfig.addWatchTarget('./_data'). Restart the server after configuration changes.
2. Inspect Exclusions: Temporarily rename .eleventyignore to test if file exclusions are blocking changes.
3. Test File Change Detection: Edit a simple template file (e.g., add a unique comment) and confirm the change appears in the final _site output directory.
4. Confirm Live Reload: If the build updates but the browser doesn't, check your BrowserSync setup. Configure it to watch the output directory: eleventyConfig.setBrowserSyncConfig({ files: ['./_site/**/*'] }).

Concrete Verification Example

If you have a data file at ./_data/config.js, and this directory is not the primary input, running npx @11ty/eleventy --serve --debug should show Watching lines that include ./_data after you explicitly added the watch target. If you edit config.js and the console logs Change detected followed by a rebuild, the watch is working; if not, the path registration is incorrect.

Escalation Criteria

If all watch targets are correctly registered, exclusions are cleared, and the build output reflects the change, the issue is likely in the client-side reload mechanism (BrowserSync). Verify the configured port is not in use by another service. If the console output from --debug does not show any file change events upon saving, the file system event hook is failing, which may require checking OS-specific file watcher permissions.

Limitations

These checks assume Eleventy version 1.0 or newer. Behavior regarding file system event handling can vary across operating systems (e.g., macOS vs. Windows).