Eleventy Dev Server Added in v2.0.0

The Eleventy 2.0 release includes a brand new development server. Check out the 11ty/eleventy-dev-server repository on GitHub.

At time of release, this new server has:

• 🏋🏻‍♀️ Minimal footprint: 1.4 MB node_modules
  • Eleventy node_modules dropped from 155 MB to 34.3 MB
  • Faster Eleventy npm install times (30.5% faster)
  • Reduced Eleventy dependency count from 311 -> 211
• 📦 Bundler Decoupled
• 🚄 Fast ~2ms startup times
• ⚡️ WebSockets-based Live reload
• 🔬 DOM-diffing HTML updates
• ⚠️ No unresolved npm audit errors or warnings 👀
• 🚤 Supports emulated passthrough file copy for faster builds!

Read more detail on the Eleventy Dev Server 1.0 release notes.

Options Jump to heading #

You can configure the server with the new setServerOptions Configuration API method.

module.exports = function (eleventyConfig) {
	eleventyConfig.setServerOptions({
		// Default values are shown:

		// Whether the live reload snippet is used
		liveReload: true,

		// Whether DOM diffing updates are applied where possible instead of page reloads
		domDiff: true,

		// The starting port number
		// Will increment up to (configurable) 10 times if a port is already in use.
		port: 8080,

		// Additional files to watch that will trigger server updates
		// Accepts an Array of file paths or globs (passed to `chokidar.watch`).
		// Works great with a separate bundler writing files to your output folder.
		// e.g. `watch: ["_site/**/*.css"]`
		watch: [],

		// Show local network IP addresses for device testing
		showAllHosts: false,

		// Use a local key/certificate to opt-in to local HTTP/2 with https
		https: {
			// key: "./localhost.key",
			// cert: "./localhost.cert",
		},

		// Change the default file encoding for reading/serving files
		encoding: "utf-8",

		// Show the dev server version number on the command line
		showVersion: false,

		// Added in Dev Server 2.0+
		// The default file name to show when a directory is requested.
		indexFileName: "index.html",

		// Added in Dev Server 2.0+
		// An object mapping a URLPattern pathname to a callback function
		// for on-request processing (read more below).
		onRequest: {},
	});
};

module.exports = function (eleventyConfig) {
	eleventyConfig.setServerOptions({
		// Show the server version number on the command line
		showVersion: false,

		// Change the name of the folder name used for injected scripts
		injectedScriptsFolder: ".11ty",

		// Number of times to increment a port is already in use
		portReassignmentRetryCount: 10,

		// Alias for backwards compatibility, renamed to `injectedScriptsFolder` in Dev Server 1.0+
		folder: ".11ty",

		// Alias for backwards compatibility, renamed to `liveReload` in Dev Server 1.0+
		enabled: true,

		// Alias for backwards compatibility, renamed to `domDiff` in Dev Server 1.0+
		domdiff: true,
	});
};

• Read more about chokidar.watch compatible paths for the watch option. Advanced chokidar configuration is available.
• For a full list of encoding values supported by Node (also used in the Content-Type HTTP Header), check out Node’s Buffer documentation.
• Using a root 404.html file (a popular convention supported by Netlify, GitHub Pages, Vercel, and others) supported! We use the content from a 404.html in your output folder when serving the error page for missing content.

onRequest for request-time processing Jump to heading #

Pre-release only: v3.0.0-alpha.7Added in Dev Server 2.0.0 Use the new onRequest object to configure some of your project to use on-request-time processing. The keys in this object represent strings from the URL Pattern API.

module.exports = function(eleventyConfig) {
	eleventyConfig.setServerOptions({
		onRequest: {
			"/": function({ url }) {
				// will fallback to serve static files if we return any falsy value other than ""
			},
			"/empty": function({ url }) {
				// render an empty page
				return "";
			},
			"/foo/:name": function({ url, pattern, patternGroups }) {
				// patternGroups will include URLPattern matches e.g. /foo/zach => { name: "zach" }
				return {
					status: 200,
					headers: {
						"Content-Type": "text/html",
					},
					body: "Hello."
				};
			}
		}
	});
}

Works great with the process.env.ELEVENTY_RUN_MODE environment variable to change how your server operates during--serve mode.

module.exports = function(eleventyConfig) {
	// Intercept all requests during --serve mode.
	if(process.env.ELEVENTY_RUN_MODE === "serve") {
		eleventyConfig.setServerOptions({
			onRequest: {
				"/*": function({ url }) {
					// Don’t return any static files, only show a help message
					return "Help I am trapped in the computer.";
				},
			}
		});
	}
}

Advanced chokidar options Jump to heading #

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

module.exports = function(eleventyConfig) {
	eleventyConfig.setChokidarConfig({
		usePolling: true,
		interval: 500,
	});
}

Swap back to Browsersync Added in v2.0.0 Jump to heading #

You can swap back to Eleventy Dev Server using the setServerOptions configuration API and the @11ty/eleventy-server-browsersync package.

First, install it:

npm install @11ty/eleventy-server-browsersync

Then, enable it in your configuration file:

module.exports = function (eleventyConfig) {
	eleventyConfig.setServerOptions({
		module: "@11ty/eleventy-server-browsersync",

		// Default Browsersync options shown:
		port: 8080,
		open: false,
		notify: false,
		ui: false,
		ghostMode: false,

		// Opt-out of the Browsersync snippet
		// snippet: false,
	});
};

View the full list of Browsersync options.

setBrowserSyncConfig Jump to heading #

eleventyConfig.setBrowserSyncConfig was the previous Configuration API method used in versions of Eleventy prior to v2. It was changed to be a no-op in Eleventy v2 (it has no functional purpose).

Other pages in Watch and Serve:

• Eleventy Dev Server
• Browsersync
• Vite