Add a `cwd` or `root` option to Eleventy core

[zachleat]

We have input (directory, file, glob) but no mechanism to change the root directory from which Eleventy runs. We always assume this matches process.cwd() which may or may not be true.

Related #1155 #3854
Marginally related #2793

[zachleat]

Impact:

• (new) root CLI param
• Configuration files (implied root)
• package.json (we look in parent dirs)
• Project directories (input, output, input informs data/includes/layouts, and in Render Plugin)
• Ignores (and related Remove support for $INPUT/.gitignore (0.7.0 added $ROOT/.gitignore) #364)
• Passthrough copy targets
• Collection API (e.g. getFilteredByGlob)
• process.env.ELEVENTY_ROOT and eleventy.env.root supplied data
• InputPath to URL plugin
• references to TemplatePath.getWorkingDir

One of the big questions for me is whether or not this should run process.chdir(directory)? My hunch is no — that would be too intrusive, but I’m open to feedback there!

[terpimost]

why don't we just fully respect --input path for all of those?

[zachleat]

@terpimost well, that would be a very big breaking change and would break a bunch of existing projects, so I don’t think we want to do that. We’ve always differentiated project root from input directory (even though the default is "." for both). This feature is more about overriding project root as being different from the directory from which you run the eleventy command in your terminal.

[terpimost]

Could you clarify if ELEVENTY_ROOT value would always reflect what eleventy things the root is?

And it would be nice to control that via some --eleventy-root parameter

[djwebdroid]

Would this cause a breaking change, from your impact post, seems to affect quit a few things. I'm no expert! But the way things work today seem fine to me. what advantages would be gained ?

[terpimost]

@djwebdroid for cases when eleventy is executed from one place, input is in another and output is in another. In some organizations with mono repos and not popular build systems (nix) ability to pint eleventy to every location involved in the build is very helpful.

[zachleat]

@djwebdroid no I wouldn’t expect these to be breaking changes for anyone. This is an opt-in feature for folks that want to run their Eleventy command from a different directory than where their project resides.

[zachleat]

@terpimost for sure! process.env.ELEVENTY_ROOT is currently available and holds the process.cwd() directory: https://www.11ty.dev/docs/environment-vars/#eleventy-supplied