Skip to navigation Skip to main content
11ty Logo Sustainability Fundraising
Eleventy
Eleventy Documentation
Stable
2.0.1
Canary
3.0.0-alpha.10
Toggle Menu
Eleventy 1.93s
Gatsby 29.05s

Passthrough File Copy

Contents

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.

Filename .eleventy.js
Output Directory _site
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");
};
INFO:
Passthrough File Copy entries are relative to the root of your project and not your Eleventy input directory.

If you do not want to maintain the same directory structure, change the output directory.

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:

If we copy src/img using passthrough file copy, it will copy to _site/img.

Filename .eleventy.js
Input Directory src
Output Directory _site
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.

Filename .eleventy.js
module.exports = function (eleventyConfig) {
// Find and copy any `jpg` files, maintaining directory structure.
eleventyConfig.addPassthroughCopy("**/*.jpg");
};

With an output directory of _site:

Change the Output Directory Jump to heading

Instead of a string, pass in an object of the following structure: { "input": "target" }.

Filename .eleventy.js
Input Directory src
Output Directory _site
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.

Filename .eleventy.js
Output Dir _site
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:

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:

Filename .eleventy.js
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".

INFO:
Note that this method is typically slower than the addPassthroughCopy configuration API method above, especially if your project is large and has lots of files.

Emulate Passthrough Copy During --serve Added in v2.0.0 Jump to heading

The Eleventy Dev Server includes a great build-performance feature that will emulate passthrough file copy.

Practically speaking, this means that (during --serve only!) files are referenced directly and will not be copied to your output folder. Changes to passthrough file copies will not trigger an Eleventy build but will live reload appropriately in the dev server.

You can enable this behavior in your project using this configuration API method:

Filename .eleventy.js
module.exports = function (eleventyConfig) {
// the default is "copy"
eleventyConfig.setServerPassthroughCopyBehavior("passthrough");
};

This behavior will revert to "copy" in your project automatically if:

  1. If you are running Eleventy without --serve (a standard build or via --watch)
  2. You change from the default development server: Eleventy Dev Server (e.g. swap back to Browsersync)
INFO:
For 2.0 canary users, note that this behavior spent a fair bit of time as the default and required opt-out from 2.0.0-canary.12 through 2.0.0-canary.30. It was changed to opt-in in 2.0.0-canary.31.

Advanced Options Added in v2.0.0 Jump to heading

Additionally, 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:

Filename .eleventy.js
module.exports = function (eleventyConfig) {
eleventyConfig.addPassthroughCopy("img", {
expand: true, // expand symbolic links
});
};
Filename .eleventy.js
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.


Other pages in Configuration: