Passthrough File Copy Jump to heading
If we want to copy additional files that are not Eleventy templates, we use a feature called Passthrough File Copy to tell Eleventy to copy things to our output folder for us.
Configuration API Method Jump to heading
Use a configuration API method to specify files or directories for Eleventy to copy.
module.exports = function(eleventyConfig) {
// Output directory: _site
// Copy `img/` to `_site/img`
eleventyConfig.addPassthroughCopy("img");
// Copy `css/fonts/` to `_site/css/fonts`
// Keeps the same directory structure.
eleventyConfig.addPassthroughCopy("css/fonts");
// Copy any .jpg file to `_site`, via Glob pattern
// Keeps the same directory structure.
eleventyConfig.addPassthroughCopy("**/*.jpg");
};
If you do not want to maintain the same directory structure, change the output directory.
Coming soon in v2.0.0Passthrough file copy is emulated when using --serve
.
How Input Directories are Handled Jump to heading
As stated above, passthrough file copy paths are relative to the project root and not the input directory. Because of this, if the passthrough file copy path is inside of your input directory, the input directory will be stripped from the output path.
For example:
input
directory issrc
output
directory is_site
.
If we copy src/img
using passthrough file copy, it will copy to _site/img
.
module.exports = function(eleventyConfig) {
// Input directory: src
// Output directory: _site
// The following copies to `_site/img`
eleventyConfig.addPassthroughCopy("src/img");
};
Using Globs Jump to heading
In this example, we copy all jpg
image files to the output folder, maintaining their directory structure. If you do not want to maintain the same directory structure, change the output directory.
Note that this method is slower than non-glob methods, as it searches the entire directory structure and copies each file in Eleventy individually.
module.exports = function(eleventyConfig) {
// Find and copy any `jpg` files, maintaining directory structure.
eleventyConfig.addPassthroughCopy("**/*.jpg");
};
With an output directory of _site
:
img/avatar.jpg
will copy to_site/img/avatar.jpg
subdir/img/avatar.jpg
will copy to_site/subdir/img/avatar.jpg
Change the Output Directory Jump to heading
Instead of a string, pass in an object of the following structure: { "input": "target" }
.
module.exports = function(eleventyConfig) {
// Input directory: src
// Output directory: _site
// Copy `img/` to `_site/subfolder/img`
eleventyConfig.addPassthroughCopy({ "img": "subfolder/img" });
// Copy `src/img/` to `_site/subfolder/img`
eleventyConfig.addPassthroughCopy({ "src/img": "subfolder/img" });
// Copy `random-folder/img/` to `_site/subfolder/img`
eleventyConfig.addPassthroughCopy({ "random-folder/img": "subfolder/img" });
};
Using Globs and Output Directories Jump to heading
Note that this method is slower than non-glob methods, as it is searching the entire directory structure and copies each file in Eleventy individually.
module.exports = function(eleventyConfig) {
// Output directory: _site
// Find and copy any `jpg` files in any folder to _site/img
// Does not keep the same directory structure.
eleventyConfig.addPassthroughCopy({ "**/*.jpg": "img" });
};
With an output directory of _site
:
img/avatar.jpg
would copy to_site/img/avatar.jpg
subdir/img/avatar.jpg
would copy to_site/img/avatar.jpg
Passthrough by File Extension Jump to heading
Eleventy, by default, searches for any file in the input directory with a file extension listed in your templateFormats
configuration. That means if you’ve listed njk
in your templateFormats
, we’ll look for any Nunjucks templates (files with the .njk
file extension).
If a file format is not recognized by Eleventy as a template file extension, Eleventy will ignore the file. You can modify this behavior by adding supported template formats:
module.exports = function(eleventyConfig) {
eleventyConfig.setTemplateFormats([
"md",
"css" // css is not yet a recognized template extension in Eleventy
]);
};
In the above code sample css
is not currently a recognized Eleventy template, but Eleventy will search for any *.css
files inside of the input directory and copy them to output (keeping directory structure).
You might want to use this for images by adding "jpg"
, "png"
, or maybe even "webp"
.
addPassthroughCopy
configuration API method above, especially if your project is large and has lots of files.Passthrough during --serve
Coming soon in v2.0.0
Jump to heading
New in Eleventy 2.0.0-canary.12
: passthrough file copy is emulated when using the Eleventy Dev Server.
Practically speaking, this means that passthrough copy files will not be copied to your output folder and will not impact local development build times. Changes made to passthrough copy files will still hot reload your web browser as expected.
This behavior will revert if:
- You use a different development server (e.g. swap back to Browsersync)
- If you are running Eleventy without
--serve
(a normal build or via--watch
)
You can also opt-out using this configuration API method:
module.exports = function(eleventyConfig) {
// the default is "passthrough"
eleventyConfig.setServerPassthroughCopyBehavior("copy");
};
Advanced Options Coming soon in v2.0.0 Jump to heading
New in 2.0.0-canary.12
, you can pass additional configuration options to the recursive-copy
package. This unlocks the use passthrough file copy with symlinks, transforming or renaming copied files. Here are just a few examples:
module.exports = function(eleventyConfig) {
eleventyConfig.addPassthroughCopy("img", {
expand: true, // expand symbolic links
});
};
module.exports = function(eleventyConfig) {
let copyOptions = {
debug: true, // log debug information
};
eleventyConfig.addPassthroughCopy({ "img": "subfolder/img" }, copyOptions);
};
Review the full list of options on the recursive-copy
GitHub repository.
Passthrough Everything Jump to heading
Given that global copy of all content in the directory may be a security risk, we do not copy anything that doesn’t match the file extensions listed in templateFormats
. Note that we do provide a command line flag to bypass this behavior: --passthroughall
. Intentionally, there is no configuration option to do this.
# Copies ALL files in the input directory to the output directory
npx @11ty/eleventy --passthroughall