package-management.md

Package Management

Like most JavaScript projects, LJAS relies on package.json which is a JSON configuration file found your project's root directory. It determines all of the meta information and dependencies for your project.

Contents

• Package Manager
• package.json Basics
  • Package Version Practices
  • Managing Dependencies
  • Scripts
• dependencies vs. devDependencies
• Troubleshooting

Package Manager

While there are multiple package managers that support package.json, we currently only support npm out-of-the-box since it is usually installed alongside Node.js. Because of this, the docs are written in the perspective of an npm user.

While LJAS has dropped support of Yarn starting from v1.x.x, we still have the todo list example ported from v0.1.1 which uses Yarn. Please note that this example is considered legacy so it will not receive significant future updates.

Switching to a different package manager shouldn't be difficult as long as you do it early, so we highly recommend that you decide on one package manager when you start a new project and stick with it to avoid issues that can arise when switching package managers later in development.

package.json Basics

Package Version Practices

All version numbers (i.e. your package version or package dependency versions) are supposed to follow semantic versioning (SemVer). Sometimes you may encounter a package that doesn't respect it which is unfortunate. Avoid being a headache for the community and please follow SemVer practices correctly!

Managing Dependencies

Install new packages with the npm install command like so:

npm install react

This command also lets you do other things. For example, you can specify which version of a package to install like so:

npm install [email protected]

You can also install multiple packages by passing in multiple arguments like so:

npm install react react-dom

When you install a package, it will add itself under the dependencies field by default, but you can add a package to different dependency category too. For example, if you want to add a development dependency, you can use a command like this:

npm install jest --save-dev

This will install Jest and add it under the devDependencies field. A shorter alternative to the --save-dev flag is -D.

If you need to update the version for existing dependency, you can use the npm update command like so:

npm update [email protected]

Uninstalling existing dependencies is done with the npm uninstall command like so:

npm uninstall react

When you need to install all dependencies during setup for a project, run the npm ci command to do so:

npm ci

This command acts similarly to running npm install without passing in any arguments except it will not perform any changes to package-lock.json.

Scripts

The scripts field allows you to define package.json scripts which become terminal commands. We provide many scripts for you to use out-of-the-box which we cover in other documents in the "Developing" section of the docs.

Here is an example of our lint script which will run ESLint and identify potential problems in your code:

npm run lint

It is a good idea to add scripts for commonly used and inconveniently long terminal commands to this field.

dependencies vs. devDependencies

LJAS organizes all packages that are required to execute the build process and application in the dependencies field like React and webpack. All other packages that aren't critical to the build process and application are placed under the devDependencies field. So for example, while ESLint and Jest are vital for development, they are not used by the application when it runs or the build process, so they would fall into this latter category.

Troubleshooting

Problems

• Some of my packages are having problems running.
• How do I figure out which packages are dependent on a specific package?

---

Some of my packages are having problems running.

When in doubt, first try deleting your existing node_modules directory. This can be done by running the following command in your project's root directory:

rm -rf node_modules

Then reinstall all of your project's dependencies.

Alternatively, you can remove the existing node_modules directory and create a brand new one using a single command called npm ci:

npm ci

---

How do I figure out which packages are dependent on a specific package?

Sometimes you need to figure out which packages are dependent on a specific package. This can be handy in situations where you need to resolve version conflicts. Sometimes looking at your package.json alone isn't enough as there could be deeper, unseen relations in your project's dependency tree that are causing problems.

A good way to figure this out is to use the npm ls command which allows you to visualize your project's dependency tree. For example, you can see which packages depend on React using the following command:

npm ls react