- Stable
3.0.0
Toggle Menu
5.81s
43.36s
Eleventy Dev Server Added in v2.0.0
Contents
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
- Eleventy
- π¦ 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
You can configure the server with the new setServerOptions
Configuration API method.
export default 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({
// 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: {},
});
};
Expand to see the Full options list
export default function(eleventyConfig) {
eleventyConfig.setServerOptions({
// 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,
});
};
module.exports = function(eleventyConfig) {
eleventyConfig.setServerOptions({
// 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 thewatch
option. Advanced chokidar configuration is available. - For a full list of
encoding
values supported by Node (also used in theContent-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 a404.html
in your output folder when serving the error page for missing content.
devcert-cli
package to generate a localhost key and certificate for https
and HTTP/2.onRequest
for request-time processing
Added in v3.0.0Added 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.
export default 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."
};
}
}
});
};
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.
export default 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.";
},
}
});
}
};
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
Access to advanced chokidar
configuration is available via the eleventyConfig.setChokidarConfig
method (on the Watch and Serve documentation).
Swap back to Browsersync Added in v2.0.0
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:
export default 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,
});
};
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
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).