search

11ty / eleventy

A simpler site generator. Transforms a directory of templates (of varying types) into HTML.
https://www.11ty.dev/
MIT License
16.84k stars 487 forks source link

Global vs local install recommendation #442

Closed denismcdonald closed 5 years ago

denismcdonald commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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:

zachleat commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@zachleat Got a chance to look at this now.

Good job, Zach.

Ryuno-Ki commented 5 years ago

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 commented 5 years ago

@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.