Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation in Tutorial Part 0 - Using the Gatsby CLI missing key info #20378

Closed
3 tasks
resource11 opened this issue Jan 2, 2020 · 11 comments
Closed
3 tasks
Labels
type: documentation An issue or pull request for improving or updating Gatsby's documentation

Comments

@resource11
Copy link
Contributor

resource11 commented Jan 2, 2020

Summary

Hello Gatsby core team! I think users working through the Gatsby tutorials will benefit from guidance on choosing npm as their default package manager to select on first run of gatsby new when starting to learn Gatsby. In addition, pointing to the page on Gatsby CLI commands will be helpful. This missing piece of info should reduce issues that occur when a user works through Tutorial Part 3 and is required to install dependencies in a project for the first time.

I'm happy to make updates to the documentation if you wish.

Some recommended topics to cover:


Motivation

Users who are brand new to using npm and/or yarn will benefit greatly from this info, here's why:

While working through the Gatsby Tutorials, I ran into an issue in Tutorial Part 3 where running gatsby develop in the cli at step 4 of the Install and configure gatsby-plugin-typography step, and threw the following error:

Error: Cannot find module 'react'

After checking the package.json file dependencies I ran yarn in the cli, and then gatsby develop. The app loaded just fine after that.

I reviewed all the tutorial steps to determine what possibly may have caused the error, and I remembered one thing: when I generated a Gastby project for the first time, I selected yarn as my default package manager (in anticipation to working with theming and yarn workspaces later in the week).

As I was following the tutorial steps, I realized I was using npm rather than yarn to install the typography dependencies. I'm not fully familiar with the issues that could happen (if any) by using yarn as your default package manager, generating gatsby projects, and then using npm to install dependencies in the project.

However. Considering the tutorial steps are indicating we should be using npm to install dependencies, it seems it makes sense to guide brand new users to select npm as their default package manager during the first run of gatsby new, yes?

Steps to resolve this issue

Draft the doc

Open a pull request

  • Open a pull request with your work including the words "closes #[this issue's number]" in the pull request description
@gatsbot gatsbot bot added the type: documentation An issue or pull request for improving or updating Gatsby's documentation label Jan 2, 2020
@sjames1958gm
Copy link

I ran into this same issue. Deleting the node_modules and running yarn resolved it.

@resource11
Copy link
Contributor Author

Indeed that will resolve the issue! My concern here is the Gatsby users that are new to yarn and npm in general.

Improving the documentation will reduce the amount of times users may get tripped up by following the tutorial steps, should they choose to select yarn vs npm as their default package manger on first run.

@LekoArts
Copy link
Contributor

LekoArts commented Jan 8, 2020

The problem you're running into is not that you're mixing yarn and npm but that npm messed up the dependencies after the install of the typography plugin. If you rerun npm install instead of yarn it'll work, too.

People that don't know yarn won't have it installed and hence the CLI will pick npm as default manager.

So all in all I think there is no need to add this instruction as it's unfortunately a bug of npm.

@marcysutton marcysutton added this to To prioritize in Documentation Roadmap via automation Jan 22, 2020
@github-actions
Copy link

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

@github-actions github-actions bot added the stale? Issue that may be closed soon due to the original author not responding any more. label Jan 28, 2020
@marcysutton marcysutton removed the stale? Issue that may be closed soon due to the original author not responding any more. label Jan 30, 2020
@github-actions
Copy link

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

@github-actions github-actions bot added the stale? Issue that may be closed soon due to the original author not responding any more. label Feb 20, 2020
@resource11
Copy link
Contributor Author

Thanks for the feedback, @LekoArts! I suppose I should rephrase: I'm familiar with both yarn and npm and how using both at once can mess up dependencies and such, however! New users who are unfamiliar and who may read/follow instructions literally can get tripped up without the clarifying instructions. 😄

I'm glad to see this is on the Learning Roadmap, @marcysutton. Let me know if you'd like me to submit a PR here...

@github-actions github-actions bot removed the stale? Issue that may be closed soon due to the original author not responding any more. label Feb 21, 2020
@laurieontech
Copy link
Contributor

@resource11 We'd definitely be open to a PR that clarifies this! Part Zero is focused on new users, so want to make it as error proof as possible.

@resource11
Copy link
Contributor Author

Excellent! I'll get started on writing something up for this. Thanks, @laurieontech!

@github-actions
Copy link

github-actions bot commented Apr 1, 2020

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

@github-actions github-actions bot added the stale? Issue that may be closed soon due to the original author not responding any more. label Apr 1, 2020
@resource11
Copy link
Contributor Author

Hey @laurieontech! I checked back on this particular section of the docs and it looks like that Part Zero clarification is already added. My apologies for not jumping on this one sooner... looks like this issue is indeed resolved now. 😄

@github-actions github-actions bot removed the stale? Issue that may be closed soon due to the original author not responding any more. label Apr 1, 2020
@laurieontech
Copy link
Contributor

laurieontech commented Apr 1, 2020

Thanks @resource11! And no worries at all. We've all been overwhelmed recently. Thanks for opening the issue and for the follow up :) I'll close it out.

Documentation Roadmap automation moved this from To prioritize to Done Apr 1, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type: documentation An issue or pull request for improving or updating Gatsby's documentation
Projects
No open projects
Development

No branches or pull requests

5 participants