The Missing README provides installation instructions for true JavaScript development beginners

README.md

The Missing README for JavaScript Projects

This README provides general instructions for installing Node.js and npm ecosystem projects from GitHub.

Many project READMEs assume a baseline level of user knowledge, but the following "Getting Started" section isn't very helpful to an absolute beginner:

Getting Started

npm install
npm start

Since I use macOS Sierra, this guide will offer help specific to macOS users. Contributions for other operating systems are welcome!

Step 0: What's a terminal?

The terminal is where you'll enter most of the one-line commands you find on project READMEs. If you're on a Mac, you have one installed already.

• Open up your terminal. The application Terminal.app comes preinstalled on macOS.
• Learn some basic Unix commands for filesystem navigation:
  • Paths on macOS (and other Unix-based operating systems) look like this: path/to/your/file.pdf
  • cd <path> will navigate you to <path>. This is like clicking through the Finder.
  • ls will list the contents of your current directory.
  • pwd will print out the absolute path to your current location (useful if you want to get an example of a path).
  • mkdir my-directory creates a directory (folder) called my-directory in your current location.
  • open . (don't forget the dot!) will open a Finder window for your current directory. Use this as an escape hatch.
  • If you have the time and interest, here is a deeper tutorial for the terminal.

Step 1: What's Git?

Git is a version control system which supports collaboration.

• Install Git.
  • You can probably also install Git by opening a terminal, typing git, and hitting Enter. A window should pop up asking if you want to install Apple's Xcode Developer Tools; go ahead and say "yes."

Note: Git vs. GitHub

Git is just software for versioning, whereas GitHub is a website people use to host git repositories (projects) for collaboration, backup, and sharing.

You don't have to use GitHub to use Git! You could just manage your changes locally (on your own machine, without connecting to the internet or any other machines).

Step 2: Download the project to your computer

Now that you have git installed, it's time to actually get a local (downloaded to your own machine) copy of the project you wanted to install in the first place.

In Git parlance, projects are called repositories, or "repos" for short.

• Navigate to the GitHub repository's homepage (the URL should look like http://github.com/some-username/project-name).

• Now, open your terminal, decide where you'd like to download the project, and cd there.

  • cd ~/Downloads will take you to your user's Downloads folder (the ~ is shorthand for "user home directory," which is typically /Users/your-login-username on macOS).

  • You can also create a new directory like ~/git:

    cd ~
    mkdir git
    cd git

• Finally, you should be in your chosen directory, and you should have the URL of the repository. Run:

  git clone <url>

  For example:

  git clone https://github.com/sarahlim/ply

• Now you have a local copy of the repo, and you can navigate into its directory:

  cd <repo-name>  # for https://github.com/user/REPO-NAME

  For example:

  cd ply  # for https://github.com/sarahlim/ply

Step 3: Install project technologies

This section is specific to Node.js/npm projects, but can be generalized to any language and ecosystem. The following instructions will probably be relevant if any of the following are true:

• The top level of the project contains a file called package.json
• The instructions in the README talk about npm or yarn

• Install Node.js by following the instructions on the website.
• If the project's README explicitly mentions any other dependencies or libraries, follow the site instructions to install those as well.

Step 4: Install the project

You're finally ready to install the actual project!

• Follow the instructions in the project README, which probably involve the following steps:
  • Run npm install inside the project
  • Run npm start afterwards

Note: npm vs. Yarn

Node.js comes with a package manager called npm, which is kind of like a free App Store for JavaScript software.

If the project's README mentions yarn, you can probably replace yarn with npm and things will go fine.

For example:

yarn install          # npm install
yarn start            # npm start
yarn run some-script  # npm run some-script

One pitfall is with global installation (installing a package to your whole computer, not just the specific project).

yarn global add some-package   # npm install -g some-package

A note about installing stuff

When you first start programming, installation and setup can be incredibly frustrating, often more difficult than the actual programming itself.

Don't be deterred! When you first begin, you'll be Googling and copy-pasting commands seemingly mindlessly. Over time, development configuration will become easier and easier, and you'll actually start to understand what each command means. Persevere, and it will all be okay.

Troubleshooting FAQ

• I typed sudo <...> and now it's asking me for my password. What password?

  The password you use to log into your account on your computer. sudo <command> is roughly equivalent to performing <command> with administrator privileges.

• I'm getting some error about my PATH.

  TODO: write this