The files used in this blog can be found here: https://github.com/PhilWolf91/blog_package_json
I’ve really been getting into VSCode recently when doing my own projects and even at work. One thing I’ve noticed is that packages seem to be handled a little differently between using something like a feature-packed IDE like Visual Studio 2015 compared to Visual Studio Code or another editor like Sublime or Brackets. In Visual Studio 2015 you generally have proj files like a .csproj and/or a .sln which would handle packages using a list of entries in a package.config file which is used by NuGet. The entries would probably look a little something like
<?xml version="1.0" encoding="utf-8"?>
<package id="angularjs" version="1.5.8" targetFramework="net452" />
<package id="bootstrap" version="3.3.7" targetFramework="net452" />
<package id="jQuery" version="1.9.1" targetFramework="net452" />
This package.config file would install angularjs, bootstrap, and jquery to a nice and tidy Scripts folder and you wouldn’t really have to worry about them again unless you wanted to update the packages. Other Developers coming onto the project would most likely already have those files in source or would be able to run a NuGet restore to get those files into their environment. Package.json works kind of in the same way except it uses packages from NPM, stores those packages in a node_modules directory, and generally come with insanely long file paths that drive Windows and myself mad (the package will have dependencies, which will have dependencies, which will have dependencies… etc, outcome = long ass file paths).
Alright… so lets start off with an empty website and lets add some basic files to start off
All of these files are empty except the .gitignore which has one entry… node_modules/
This is because node_modules shouldn’t be placed into source and only on the machines that will be developing the app or the server running the app (so part of the build/deployment process would be to run ‘npm install’ so that all the dependencies are available on deployment)
Ok. So what the hell do we do now? We’ve got an empty package.json file… what goes in it? Well, with a little help from VSCode’s intellisense… it’s pretty easy to know what can go in this file along with some help from NPM’s documentation located here https://docs.npmjs.com/files/package.json.
As its a JSON file, you might be able to infer that you’d start off with some squiggly brackets and that properties will be listed in normal JSON format using “property”: “value”… so what happens when we attempt to add a new property?
Well hi there intellisense, long time no see, are those the properties I can use in the file? Why yes, yes they are. I can see two properties already that’ll be helpful, 1) author and 2) dependencies. So if we begin to enter author, we’ll see what this property is suppose to contain in terms of it’s value.
OK Cool, so the author property is supposed to include information about me. Now, in your own project you don’t really need to add this property as its really more helpful for when you actually put a lib on NPM so people can know who created the package as that’s what you’re essentially doing by using package.json, you’re entire project is now technically a ‘package’. Filling out the author though intellisense will allow you to tab-complete a new object for its value so once that’s done you can then start to add properties of the object belonging to ‘author’
As you can see, the object that belongs to ‘author’ contains email,name, and url properties. Lets fill those out really quick. After adding those properties to the object ‘author’ will be happy it has been given the correct data. But you may notice there is a green squiggly under the very first bracket… why is this?
Looks like the package.json file is looking for two properties right off the bat that we don’t have, lets go ahead and add those. After seeing how the author property was added, you should be able to have intellisense help you add these two properties. You should end up with something that looks like this:
Ok. So that’s nice, we’ve got this information in our package.json but… WHAT ABOUT THE DEPENDENCIES?!?!? That’s what you’re here for in the first place, right?
Adding Dependencies to your package.json file
So if you read Getting Started section you’ve been exposed to the intellisense provided by VS Code in the package.json file and you might be able to conclude that intellisense will also help us with adding dependencies… you’d be correct. Remember seeing dependencies in the intellisense from before? Lets try adding that property now.
By clicking on the blue ? icon next to ‘dependencies’ when intellisense pops up, you’ll see the full version of the description for this property. Ok, so this property contains the dependencies of our package AKA our project. Let’s tab complete it and see what we get.
Alrighttttt, so this is where intellisense abandons us, and for good reason… there’s a shit ton of packages out there and trying to fit them all in that intellisense window would be kind of asinine and probably be a humongous load to handle. So, in order to begin adding the dependencies we want, we have to go checkout npmjs.com for the packages we need. So say we want Angular…
That first package looks right to me, lets add it to the dependencies. Add “angular”: “” under dependencies and that will tell package.json to install any version of angular available, which means it will choose highest version it can find and install it.
What if we want a specific version, or, near a specific version if that version cannot be found? Well, intellisense can actually help us out here but it requires the first number and decimal to pick up. We can see the current version on npmjs, the screenshot above shows that angular is currently on 1.5.8 so lets start to define the version as 1.5.8… but wait… what is that intellisense?
VSCode can pick up on the rest of version… but sometimes there are different options that’ll show up here. Sometimes you’ll get the prefixes on the version to appear to which show how can infer which version to use based on a specific version. Here’s the documentation from npmjs.com to show you your available options for versions:
So we now know that we can do a lot of different things when specifying the version such as expecting an exact version, multiple ways to choose a version close to the one we specify using > and < variants as well as using git repositories to get packages instead of NPM’s repository. Lets try finishing the angular dependency by using an exact version then adding another dependency to jQuery but use a variant of the version selector.
Intellisense on jQuery is giving me the option to use the approximate version, so lets give that a shot. Ok. Cool. How do we actually install these dependencies now?
Installing your dependencies
If you’ve followed through this far, you might realize I’ve made a mistake. The version needs to be in a specific format for node, something like v1.0.0 instead of 1.0 so lets go ahead and change that now.
After you’ve filled out your package.json with the dependencies (and fixed the version number!) all you have to do is run ‘npm install’ through the command prompt or a terminal. I prefer using VScode’s built in terminal which can be opened by pressing CTRL + ` (backtick) at the same time.
If you look in the TERMINAL window in bottom-middle of the screen you can see ‘npm install’ was ran, a few errors about missing details in the package.json file which aren’t required and the packages were installed. Looking at the Explorer pane on the right you can see that there is now a node_modules directory with angular and jquery installed.
Congratulations – You’ve officially created your first package.json file and installed dependencies onto your machine!