feat(create): better detection of package manager preference #6679

lex111 · 2022-02-14T20:21:33Z

Motivation

Currently create-docusaurus is counterintuitive and quite opinionated. Suppose if I run the npx create-docusaurus@latest my-website classic command, then install the dependencies for the new project is done via yarn instead of npm (as I probably expect since I used npx/npm, not yarn).

I guess we need to stop forcing the initializing of the new project only via yarn. Although, previously I had added the ability to initialize a project via npm (eg, npx create-docusaurus@latest my-website classic --use-npm), but I did this for my own purposes, to make it easier to test new releases for my self.

However, looking at other projects like Create React App or Vite, I now understand that the used package manager should be taken into account when initializing the new project. If I use npm/npx -- the deps for the new project must be installed via npm, if I use the yarn create ... command -- the deps must be installed via yarn, etc.
So I also added support for pnpm as a pretty good alternative to npm/yarn.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Locally testing or canary should work.

Related PRs

netlify · 2022-02-14T20:26:50Z

✔️ [V2]

🔨 Explore the source changes: ba48fd6

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/62164a7679dfda000a679be9

😎 Browse the preview: https://deploy-preview-6679--docusaurus-2.netlify.app

github-actions · 2022-02-14T20:27:57Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	50
🟢 Accessibility	100
🟢 Best practices	92
🟢 SEO	100
🟢 PWA	90

Lighthouse ran on https://deploy-preview-6679--docusaurus-2.netlify.app/

github-actions · 2022-02-14T20:32:48Z

Size Change: +478 B (0%)

Total Size: 782 kB

Filename	Size	Change
`website/build/assets/js/main.********.js`	590 kB	+478 B (0%)

ℹ️ View Unchanged

Filename	Size
`website/.docusaurus/globalData.json`	48 kB
`website/build/assets/css/styles.********.css`	106 kB
`website/build/index.html`	37.6 kB

_{compressed-size-action}

Josh-Cena · 2022-02-15T01:23:44Z

website/docs/installation.md

@@ -17,7 +22,6 @@ Use **[docusaurus.new](https://docusaurus.new)** to test Docusaurus immediately

 - [Node.js](https://nodejs.org/en/download/) version >= 14 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed.
  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged.


Not sure about this. In my experience, using NPM has not been totally harmless. For example, #6073 is exactly caused by NPM doing something fishy. It's better if we can recommend good practices.

Josh-Cena · 2022-02-15T01:25:26Z

website/docs/installation.md


 ```bash
+# Modern way available since npm v6+
+npm init docusaurus website classic


See #5797. Generally I don't think that's a problem because the user can use the interactive prompting to provide options anyways, but it's better if we can be always safe.

I'm not a fan of documenting multiple versions across our doc, or cluttering it with too many tabs and options.

"npx" is the only one that works well across node/npm versions without added complexity

Wouldn't it be odd if we use npx in some places and npm init in other places?

See for example TS: https://docusaurus.io/docs/typescript-support#initialization

npx create-docusaurus@latest my-website classic --typescript

This is hard to convert to npm init in a way that works for both npm6/7

Let's not change something that works. Most users are happy with npx and nobody complained with this doc for a while.

This is confusing that we say "npx" is outdated and we use it in many places

Power users that know their package managers can still decide themselves to use npm init or yarn create and I'm ok to force a specific package manager in this case

I just liked describing the possible options for initializing a new project, as was done in the CRA docs. Perhaps not all users know about yarn create, even if they use yarn. Alright, I'll delete it, but what about the paragraph with the yarn requirement, it doesn't need to be reverted?

I also believe some more exhaustive documentation is necessary in at least one place. The typescript support documentation is only meant to be a brief example that works, but we can't be like "be exhaustive everywhere or be exhaustive nowhere".

what about adding tabs in a details/summary component?

I just really want to avoid cluttering the doc with info that most users don't need to see.

Usually it's a one-shot to generate the project, it's not that important to document deeply everything and is actually harmful. Frontend devs know how to delete a lockfile and generate it again with another package manager. Non-dev users will just have npm and don't care about alternatives.

Something worth mentioning:

CRA users are usually devs

Docusaurus has a lot of non-dev users that don't even know what npm is anyway

what about adding tabs in a details/summary component?

Oh, that's a good idea, added to the very end of the section.

Docusaurus has a lot of non-dev users that don't even know what npm is anyway

Well I would not say so, in fact Docusaurus is also very much used by [open-source] developers.

Frontend devs know how to delete a lockfile and generate it again with another package manager

Yes, but a developer needs to do one unnecessary action then, it is not very user-friendly in general.

Josh-Cena · 2022-02-15T01:29:26Z

website/docs/installation.md

+# Modern way available since npm v6+
+npm init docusaurus website classic
+
+# Outdated way available since npm v5.2+
 npx create-docusaurus@latest website classic


npx is the only command commonly known to execute a package script from the NPM registry which doesn't permanently install it locally, so in #5797 npm init/yarn create was replaced with this. It was not meant to mean "npm", although we do know that npm provides this command. In Yarn berry there's yarn dlx, but it's not that popular.

Josh-Cena

Choosing a default package manager is not an easy thing to do... We choose to default to Yarn whenever possible because we just feel that Yarn is objectively a better package manager than NPM, and it's also used by ourselves, which means the chances that package managers freaking out will be the lowest for Yarn (for example, it's the most lenient towards unmet peer dependencies).

npm init and yarn create are certainly indicative enough of package manager preferences, but npx was only written there because npm init doesn't work in all cases. We meant to make it a replacement for both npm init and yarn create. In this case, I don't want to default to NPM.

The thing I like about this PR is being able to use PNPM as default, as mentioned in #6631. Maybe we should also recursively look up the directories and try to find a lockfile? Does that make sense in all cases?

Josh-Cena · 2022-02-15T03:24:12Z

packages/create-docusaurus/src/index.ts

+  return (
+    SupportedPackageManagers.find((packageManager) =>
+      process.env.npm_config_user_agent?.startsWith(packageManager),
+    ) || 'npm'


At least, I don't want to use NPM as fallback but rather use the heuristic we had before. For example, I do have create-docusaurus installed globally, and if I run create-docusaurus without a package manager, it defaults to NPM with no way for me to select Yarn.

I think we can have three layers of heuristics:

Detect lockfiles. For example, the existence of a pnpm-lock.yaml or package-lock.json in a parent/grandparent folder is indicative enough that we are installing in an existing project.

If this is a standalone project, use the npm_config_user_agent except when the command is initiated by npx.

If the user is executing a global create-docusaurus, or if the command is using npx, we look for yarnpkg in the PATH.

I agree that lock files do need to be considered, but I'm still not sure about using yarn as the default option. If Docusaurus should play equally well with any popular package manager, then using npm as default seems like the most reasonable or predictable as default option. This is well illustrated by the CRA, on whose behavior Docusaurus is based right now. However, since latest major release of CRA, they started to use yarn if end user initialized the new project via it, in all other cases npm is used (including npx). That's why I suppose we also need to adjust the current process of initializing in similar way -- it's more reasonable and expectable.

Oh, I wasn't following the latest CRA, but interesting to know that they default to NPM now... In that case, I think maybe we should also add an optional --pkg-manager option and replace --use-npm with that, otherwise the user can only halt the installation and manually install again in case the pkg manager detection is not good? I'm trying to push back on NPM because I do have some personal opinions about it😅

An option like the --pkg-manager might be a good idea, but in my opinion it would require more effort to implement, so within this PR I would only improve "detection mechanism" for package manager. --use-npm is more like a temporary workaround that may no longer be needed after this PR.

I do have some personal opinions about it

Haha, I understand it, I have sort of a similar feeling, but we need to consider the interests of users first.

Josh-Cena · 2022-02-15T09:23:55Z

packages/create-docusaurus/src/index.ts

+  const packageManagerFromLockFile = packageManagers.find((packageManager) =>
+    fs.existsSync(
+      path.resolve(process.cwd(), SupportedPackageManagers[packageManager]),
+    ),
+  );


Should we look up a few folders? In case the user is creating the website at packages/website and the lock file is at the monorepo's root.

It is assumed that the starter command will be running from the root of project in any case. So I didn't want to complicate the process with this at the moment.

Sure. create-docusaurus is not very well-documented now, there are some interesting features that few users know. I'll probably improve that later

slorber · 2022-02-17T14:55:53Z

What I understand is that, if I have npm + yarn installed, running this command will always use npm now right?

npx create-docusaurus@latest my-website classic

Personally, I don't really like it that much.

If I installed yarn, it's usually because I like it better than npm.

It's not like I have the possibility to install only yarn and not npm: it's either just npm, or both.

And we have a --use-npm option, so if it defaults to npm it's a bit dumb to only have this one and not --use-yarn instead

I'm ok to use the current package manager in case of npm init or yarn create, but IMHO the current behavior of npx create-docusaurus is fine and we should not change it unless someone complains about it with strong arguments (and so far nobody complained afaik)

Josh-Cena · 2022-02-17T15:00:06Z

I'm ok to use the current package manager in case of npm init or yarn create, but IMHO the current behavior of npx create-docusaurus is fine and we should not change it unless someone complains about it with strong arguments (and so far nobody complained afaik)

Well, Alexey complained😆 (Although I'm not sure as of why)

And yes, I agree here that "It's not like I have the possibility to install only yarn and not npm: it's either just npm, or both." That was essentially my stance.

lex111 · 2022-02-17T15:41:55Z

npx is a tool introduced by npm. So it seems quite logical that by initializing a new project via npx, the dependencies will be installed via npm. The fact that React-based tools like Create React App, Create Next app, Create Remix work this same/equal way should demonstrate us that this is better behavior, adopted in the community, in comparison with using yarn by default in npx context.

slorber · 2022-02-17T16:03:17Z

Ok, let's do this then

Do we only want to document yarn create in the intro doc then, or do we want to update this in multiple places?

…rter-deps

lex111 · 2022-02-17T18:06:15Z

To keep docs as clean as possible, it's best to place new information only on the Installation page.

Josh-Cena · 2022-02-22T09:18:08Z

Can we also investigate #5182 and see if it's relevant today? Maybe also making pnpx supported in our create script, if it isn't already?

lex111 · 2022-02-22T14:36:54Z

According to the docs https://pnpm.io/pnpx-cli, this command is deprecated, although currently it can be used to initialize a new project via running pnpx create-docusaurus site, any way I guess this is irrelevant issue.

Josh-Cena · 2022-02-23T09:29:05Z

Okay, looks like pnpm dlx should be already taken care of in this PR...

lex111 · 2022-02-23T09:46:56Z

Even using pnpx, npm_user_agent env var will be defined as pnpm (similar to npx), so don't worry about that.

Josh-Cena · 2022-02-23T14:50:09Z

packages/create-docusaurus/src/index.ts

+async function getPackageManager(
+  forceUseNpm?: boolean,
+): Promise<SupportedPackageManager> {
+  if (forceUseNpm) {


Add a TODO comment about allowing a package manager option to replace the --use-npm option?

refactor(create): respect user package manager

8c96705

lex111 added the pr: polish This PR adds a very minor behavior improvement that users will enjoy. label Feb 14, 2022

lex111 requested review from slorber and Josh-Cena as code owners February 14, 2022 20:21

facebook-github-bot added the CLA Signed Signed Facebook CLA label Feb 14, 2022

Josh-Cena reviewed Feb 15, 2022

View reviewed changes

Josh-Cena changed the title ~~refactor(create): respect user package manager~~ feat(create): respect user package manager Feb 15, 2022

Josh-Cena reviewed Feb 15, 2022

View reviewed changes

Add support for lockfiles

86c0818

Josh-Cena reviewed Feb 15, 2022

View reviewed changes

Josh-Cena changed the title ~~feat(create): respect user package manager~~ feat(create): better detection of package manager preference Feb 15, 2022

lex111 added 2 commits February 16, 2022 17:56

Remove alternative install options

664c61b

Add alternative installation methods (again)

5b5715b

Merge branch 'main' of github.com:facebook/docusaurus into lex111/sta…

73b689d

…rter-deps

Merge branch 'main' into lex111/starter-deps

48a34a4

minor refactor + fix lint and use fs async

efbe5a9

slorber approved these changes Feb 23, 2022

View reviewed changes

Josh-Cena reviewed Feb 23, 2022

View reviewed changes

minor refactor + fix lint and use fs async

ba48fd6

slorber merged commit 26d223d into main Feb 23, 2022

slorber deleted the lex111/starter-deps branch February 23, 2022 15:22

Josh-Cena mentioned this pull request Feb 24, 2022

feat(create): new --package-manager option; interactive package manager selection #6750

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(create): better detection of package manager preference #6679

feat(create): better detection of package manager preference #6679

lex111 commented Feb 14, 2022

netlify bot commented Feb 14, 2022 •

edited

github-actions bot commented Feb 14, 2022 •

edited

github-actions bot commented Feb 14, 2022 •

edited

Josh-Cena Feb 15, 2022

Josh-Cena Feb 15, 2022

slorber Feb 16, 2022 •

edited

lex111 Feb 16, 2022

Josh-Cena Feb 16, 2022

slorber Feb 16, 2022 •

edited

lex111 Feb 16, 2022

Josh-Cena Feb 15, 2022

Josh-Cena left a comment •

edited

Josh-Cena Feb 15, 2022 •

edited

lex111 Feb 15, 2022

Josh-Cena Feb 15, 2022

lex111 Feb 15, 2022

Josh-Cena Feb 15, 2022

lex111 Feb 15, 2022

Josh-Cena Feb 15, 2022

slorber commented Feb 17, 2022

Josh-Cena commented Feb 17, 2022

lex111 commented Feb 17, 2022

slorber commented Feb 17, 2022

lex111 commented Feb 17, 2022

Josh-Cena commented Feb 22, 2022

lex111 commented Feb 22, 2022

Josh-Cena commented Feb 23, 2022

lex111 commented Feb 23, 2022

Josh-Cena Feb 23, 2022

slorber Feb 23, 2022

feat(create): better detection of package manager preference #6679

feat(create): better detection of package manager preference #6679

Conversation

lex111 commented Feb 14, 2022

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Feb 14, 2022 • edited

github-actions bot commented Feb 14, 2022 • edited

github-actions bot commented Feb 14, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber Feb 16, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber Feb 16, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Josh-Cena left a comment • edited

Choose a reason for hiding this comment

Josh-Cena Feb 15, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber commented Feb 17, 2022

Josh-Cena commented Feb 17, 2022

lex111 commented Feb 17, 2022

slorber commented Feb 17, 2022

lex111 commented Feb 17, 2022

Josh-Cena commented Feb 22, 2022

lex111 commented Feb 22, 2022

Josh-Cena commented Feb 23, 2022

lex111 commented Feb 23, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Feb 14, 2022 •

edited

github-actions bot commented Feb 14, 2022 •

edited

github-actions bot commented Feb 14, 2022 •

edited

slorber Feb 16, 2022 •

edited

slorber Feb 16, 2022 •

edited

Josh-Cena left a comment •

edited

Josh-Cena Feb 15, 2022 •

edited