Setting up a JavaScript project

If you're new to JS, you've probably been hit with some confusion around package.json files, why you can't just run JS files from your terminal without hitting MODULE_NOT_FOUND errors, and wondering what the deal is with needing to npm install when you first clone a seemingly simple app to your local machine. I know I was, and so I'm going to demystify setting up a JS project into is separate "whys".

JavaScript is a little different than other languages in that it runs in the browser. That's great if you're simply developing JavaScript to run exclusively in the browser, but what if you want to TDD your JavaScript and run it on your local machine? What if you want to write server-side JavaScript that runs on a server? This is where Node steps in.

Node is a JavaScript runtime environment that requires some extra configuration in order to work. It needs to know metadata about your app before it can run, at a bare minimum, it needs to know the name of the app and its version. It reads this metadata from a file called package.json, and without that file, Node can't run your JavaScript code. So in order to run JavaScript anywhere outside of the browser relying on Node, you need to make a package.json file.

The way to do this is to run npm init from your command line.

You will see a message starting with This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

Several questions will pop up, for example asking what license it is under, the name of who made it, entry points, and other things. You can fill in as much or as little of this as you'd like, but the package.json will still create even if you leave all the optional fields blank.

In the end, you'll end up with a file that looks something like this:

{
  "name": "blog",
  "version": "1.0.0",
  "description": "a test package",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Akira Brand",
  "license": "MIT"
}

Now, you need to install your dependencies. Run npm install + libraryName for any external libraries you are using in your project. This will add their metadata to the package.json file, so that whomever ends up running your project on their local machine can run npm install and have all the dependencies installed together so that your project can run.

For example, if I need to use express in my app, I would now run npm install express. Then the package.json file looks like this:

{
  "name": "blog",
  "version": "1.0.0",
  "description": "a test package",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Akira Brand",
  "license": "MIT",
  "dependencies": {
    "express": "^4.17.1"
  }
}

Notice there is now an express version at the end of the package.json file.

It's good to note now that two more files/folders have arrived in your filetree, package-lock.json and node_modules. Those are different topics for a different post, but just know that they help manage the tooling around the npm packages you've just installed. Node_modules in particular can get really large, so use good judgment on committing it to GitHub along with your project!

The node documentation does a great job of explaining package.json in further detail.

Happy projecting!