Eleventy: Global vs local install recommendation

[denismcdonald]

Just from a layperson's or hobbyist's perspective, I'm wondering about the way in which a global install of 11ty is recommended, or prioritised, both under the "Quick Start" heading and in the documentation, under "Getting Started":

npm install -g @11ty/eleventy

Only if one clicks the link, "Read more about local installation" does one then see:

# this is not preferable
npm install -g @11ty/eleventy

I suppose there's just a sense in which this sequence of things could be taken as being akin to saying:

1. "First, let's begin by doing This Thing."
2. "However, now having done This Thing, you probably shouldn't have!"

Once again, I'm not a developer, but if this were a reasonable point to make, perhaps an earlier note, or an aside, could foreshadow this distinction for users, between global and local installations, so that they don't stumble into a global install, only to then discover that 11ty is recommending otherwise?

[kleinfreund]

I tend to agree with you, but there is an important reason why prioritizing the global installation is logical:

Installing Eleventy locally in your project requires a package.json file to manage project dependencies (Eleventy being one such dependency in this case). Although it is easier to maintain projects with local dependencies (and therefore preferable), it is more cognitive load for the user. In essence, people’s goal for using Eleventy is building a static website. Having project-specific tooling be part of the project files is a new concept for some users and might end up being more confusing than helping.

However, I think documents like Getting started should offer both ways right away. I do think the current priorization of the global installation strategy is too strong.

[denismcdonald]

I'm grateful for that explanation, actually. For yes, I think my own cognitive load became a little uncomfortable when, installing locally, I learned of the size and contents of the node_modules folder (which, naturally enough, led to an impression that ran counter to Eleventy being "simpler"!). So I can see it from your point of view now, knowing a little more about both options. Thanks for that.

[Ryuno-Ki]

The problem I personally have with global installation of npm packages (being a developer) is that it can be causing conflicts among different projects.

Imagine I'd open an agency shipping Static Sites for eCommerce company. Say, as prep for a Black Friday.
Now if I have eleventy installed globally, I can't have one project upgraded and the other one not.
Thus, I use a local installation whenever feasible.

Often I hear the argument for a global installation of a npm package, that it allows you to call the CLI of the package from the command line.
You could also have it in the package file and use it as a run-command.
That is:
eleventy: eleventy in scripts of the package.json allows you to execute it with npm run eleventy instead of just eleventy.

[d2s]

_Local first_ -approach would make sense for being the baseline for the documentation, even while some individual users might use Eleventy with a system-wide _global mode_ installed package. For most of the workflows, local install (in a local node_modules directory) makes more sense, even while it requires slightly more disk space (if person has a lot of different projects).

"Rule of thumb: If your project depends on a package, it should be listed in your package.json file as a dependency and installed locally in your project, rather than globally.

_Why Shouldn’t I Install Dependencies Globally?_
The obvious short answer is that your project _depends_ on them."

— The Issue With Global Node Packages — Smashing Magazine

_Related:_

• npm-install | npm Documentation

[zachleat]

There is a third way, using npx: npx -p @11ty/eleventy eleventy. Dunno if that’s preferable to global install or not, but it may be less confusing since it doesn’t stick around as long? Not sure.

[zachleat]

So I revamped a bunch of stuff after reading this issue and answering one too many questions that resulted in us finding out that the user had a really old version of Eleventy installed globally that was being used accidentally.

https://github.com/11ty/11ty.io/commit/3c0a51861117bc751b60712c8fdfb6c3c5c75a1d

Note the 3-line quick start still uses global installation (on https://www.11ty.io/)

But these changed (local install is now default on Getting Started and Usage):

https://www.11ty.io/docs/getting-started/
https://www.11ty.io/docs/usage/

I switched the side-docs about the alternative method to be about global install instead of local install https://www.11ty.io/docs/global-installation/

I think this is a good start. Please review and let me know if you have feedback.

(cc @SaraSoueidan per our discussion)

[zachleat]

This is an automated message to let you know that a helpful response was posted to your issue and for the health of the repository issue tracker the issue will be closed. This is to help alleviate issues hanging open waiting for a response from the original poster.

If the response works to solve your problem—great! But if you’re still having problems, do not let the issue’s closing deter you if you have additional questions! Post another comment and I will reopen the issue. Thanks!

[kleinfreund]

@zachleat Got a chance to look at this now.

• Love, love, love adding the current working directory as non-selectable text. Might need some investigation on how to make this screen-reader-accessible, but syntax-highlighted code blocks might be a screen reader nightmare anyway due to span soup which leads to short pauses when announcing text (as far as I know).
• All in all, I like the getting started page. I assume the npx line allows one to run a local eleventy rather than going through the hassle of calling ./node_modules/@11ty/eleventy/cmd.js?
• In command line usage: "Searches the current directory, outputs to ./_site" — Maybe "Processes" is a better term here?

Good job, Zach.

[Ryuno-Ki]

on how to make this screen-reader-accessible, but syntax-highlighted code blocks might be a screen reader nightmare anyway

Not sure, what you are referring to here. If it is the highlight of colours in STDOUT/STDERR, maybe introduce a --no-colour flag.

If it were about the rendered markup, make the user opt in to use prism.js via JavaScript? (I plan to do that). In that case, the issue should be filled against https://github.com/11ty/eleventy-plugin-syntaxhighlight ?

[kleinfreund]

@Ryuno-Ki I’m talking about the current working directory being added to sh/bash commands as pseudo content. As far as I know, pseudo content is not announced by screen reader; hence, it would not be accessible to screen reader users.