Skip to navigation Skip to main content
Blog
Eleventy, 2024 in Review
Versions
Stable
3.1.2
Canary
4.0.0-alpha.4

Watch Files and use Development Servers

On this page

Running Eleventy with --serve starts a hot reloading local development server for you.

A development server is optional! Using --watch will run Eleventy (and re-run when you save your files) without a server.

Eleventy Dev Server Added in v2.0.0

Eleventy bundles its own dedicated Development Server. In versions prior to v2, we used Browsersync, which you can still use with Eleventy if you’d like.

For most use cases, the default behavior of this server should handle most things automatically. Changing files in your local environment will re-run an Eleventy build and refresh any active web browser sessions on the local site.

Add Your Own Watch Targets

The addWatchTarget config method allows you to manually add a file or directory for Eleventy to watch. When the file or the files in this directory change Eleventy will trigger a build. This is useful if Eleventy is not aware of your project-specific external dependencies.

eleventy.config.js
export default function(eleventyConfig) {
	eleventyConfig.addWatchTarget("./src/scss/");
};
module.exports = function(eleventyConfig) {
	eleventyConfig.addWatchTarget("./src/scss/");
};

Advanced usage note: This works with chokidar under the hood and chokidar uses picomatch for globbing:

  • Both **/*.(png|jpeg) and **/*.{png,jpeg} are valid globs to matches any png or jpeg file in your project.

Reset configuration Added in v3.0.0

We do automatically look for dependencies in your configuration file based on JavaScript require or import—watch targets not included in that dependency graph will not reset or re-run your configuration automatically.

To reset your configuration for a specific watch target, use the resetConfig option.

eleventy.config.js
export default function(eleventyConfig) {
	// You probably don’t need this
	eleventyConfig.addWatchTarget("./_config/**", {
		resetConfig: true
	});
};
module.exports = function(eleventyConfig) {
	// You probably don’t need this
	eleventyConfig.addWatchTarget("./_config/**", {
		resetConfig: true
	});
};

Reload without running a build

Use the watch option configurable with Eleventy Dev Server to refresh your local browser when local files change without triggering an Eleventy build. This is useful to decouple build processes outside of Eleventy.

Ignore Watching Files

.gitignore

Eleventy will ignore changes to files or folders listed in your .gitignore file by default, unless setUseGitIgnore is turned off.

Configuration API Added in v2.0.0

Previously, the configuration API ignores for template processing were also used as ignores for watching (e.g. eleventyConfig.ignores.add("README.md")).

New in v2.0.0, watch target ignores now have their own dedicated API:

eleventy.config.js
export default function(eleventyConfig) {
	// Do not rebuild when README.md changes (You can use a glob here too)
	eleventyConfig.watchIgnores.add("README.md");

	// Or delete entries too
	eleventyConfig.watchIgnores.delete("README.md");
};
module.exports = function(eleventyConfig) {
	// Do not rebuild when README.md changes (You can use a glob here too)
	eleventyConfig.watchIgnores.add("README.md");

	// Or delete entries too
	eleventyConfig.watchIgnores.delete("README.md");
};

The watchIgnores Set starts with a default **/node_modules/** entry.

Watch JavaScript Dependencies

When in --watch mode, Eleventy will spider the dependencies of your JavaScript Templates (.11ty.js), JavaScript Data Files (.11tydata.js or _data/**/*.js), or Configuration File (usually eleventy.config.js) to watch those files too. Files in node_modules directories are ignored. This feature is enabled by default.

eleventy.config.js
export default function(eleventyConfig) {
	// Enabled by default
	eleventyConfig.setWatchJavaScriptDependencies(false);
};
module.exports = function(eleventyConfig) {
	// Enabled by default
	eleventyConfig.setWatchJavaScriptDependencies(false);
};

Add delay before re-running

A hardcoded amount of time Eleventy will wait before triggering a new build when files have changes during --watch or --serve modes. You probably won’t need this, but is useful in some edge cases with other task runners (Gulp, Grunt, etc).

eleventy.config.js
export default function(eleventyConfig) {
	// default is 0
	eleventyConfig.setWatchThrottleWaitTime(100); // in milliseconds
};
module.exports = function(eleventyConfig) {
	// default is 0
	eleventyConfig.setWatchThrottleWaitTime(100); // in milliseconds
};

Advanced chokidar Configuration

Advanced chokidar options can be defined using the setChokidarConfig configuration API method:

eleventy.config.js
export default function(eleventyConfig) {
	eleventyConfig.setChokidarConfig({
		usePolling: true,
		interval: 500,
	});
};
module.exports = function(eleventyConfig) {
	eleventyConfig.setChokidarConfig({
		usePolling: true,
		interval: 500,
	});
};
WARNING
If you’re using Windows Subsystem for Linux (WSL) and your project exists outside of your home directory (~), you will likely want to use the usePolling feature to ensure watching works correctly. This is a WSL limitation.

Other pages in Eleventy Projects