How to Create and Distribute an npm Package

[MUSIC] 0:00 Hello, I'm Andrew, and welcome to this workshop where we'll take a look 0:04 at how to build and distribute a package with npm. 0:08 Npm is a package manager both for the browser and 0:11 server side JavaScript projects. 0:15 If you're unfamiliar with the basic usage of npm, 0:17 you should check out our npm basics course linked in the teacher's notes. 0:20 Npm is used by companies and 0:24 open source developers to distribute their code for others to use. 0:26 Companies distribute nodes modules to interact with their API. 0:30 And developers create and 0:34 distribute utilities or packages that they think may be useful for others. 0:35 If you have JavaScript code that you want to share with other JavaScript developers, 0:40 you can use npm to distribute it. 0:45 Whilst there is nothing stopping you from publishing any JavaScript code to npm, 0:47 the only reason you should be publishing a package is for 0:51 other people to use as a dependency. 0:54 Like a node module or a command line utility. 0:57 In fact, more and 1:00 more developers are using npm as a way to distribute their JavaScript projects. 1:01 For example, 1:06 j query recommends that developers distribute their tokens via npm. 1:07 Also, check the npm code of conduct for package restrictions and more guidelines. 1:12 To distribute a package on npm, 1:17 firstly you've got to create an account with the npm website. 1:19 It's free and you just need to supply your email address. 1:24 Next, you open up a a command line till like the command prompt on Windows or 1:28 the terminal on a Mac on your local machine. 1:33 And use the login command on npm to login. 1:35 We need to make sure that we have a package.json file 1:38 with all the correct information filled in. 1:41 To make sure that our package .json file is correct, 1:43 we can test that it is by locally installing the package that we've created. 1:47 Once we're happy that the package runs correctly, we can publish it. 1:51 Let's take a look at the process on my local machine. 1:55 If you want to look at this curtain and follow along. 1:58 You can download the files under the download tab on this page. 2:00 However, don't publish this same code. 2:04 I've already published it on npm. 2:07 On the other hand, if you have your own JavaScript package and 2:08 you want to publish that, then follow along with your own code, and 2:12 then publish it to the npm repository. 2:15 The package I want to distribute provides a simple way to retrieve the latest 2:19 information about posts being published on the Treehouse blog. 2:23 I have a blog.js file which includes all the coding for this package. 2:27 There's a readme file that contains the basic usage of the package, and finally 2:31 there's a gitignore file making sure that we don't check in the node modules folder. 2:36 This is the get, you don't want to be checking this in. 2:41 Npm ignores the node modules folder anyway when you publish your package. 2:44 My programming depends on another package, libxmljs, 2:48 libxmljs needs to be compiled on the local machine running the package. 2:53 This is another reason why you don't want to check in your node modules folder. 2:58 It may run a care on the Mac OS 10 operating system, but 3:02 it won't run on a Linux machine. 3:06 Each different operating system requires you to compile for that given system. 3:09 Running npm install will trigger the installation and 3:13 compilation of any dependencies for that system. 3:16 Here I am on the npmjs.com website, the official site for npm. 3:20 You need to login to the site before you can upload your package to 3:25 npm central repository. 3:30 Complete this form with your information, but be mindful down here. 3:32 Your email will be shown with all packages that you publish. 3:36 This is so that if there's an issue with your package, someone can contact you and 3:39 give you the details of the issues that they're having. 3:43 Once you're done filling in this form, submit it and follow any additional steps. 3:47 Now that you're signed up on the npm site, we can login or 3:53 authenticate in the command line application npm. 3:57 When you login to npm in the command line, 4:01 it opens up new features like the ability to publish a package. 4:03 I'm in the project folder right now, and 4:07 the most important part of an npm package is the package.json file. 4:09 Let's create it using the npm init command. 4:13 Values in brackets are default values that npm guesses. 4:16 Treehouse_blog seems like a sensible name. 4:22 Version one? 4:25 Sure. 4:26 Description? 4:27 I'm going to lift that from the README file. 4:29 The entry point is the main file of your package. 4:41 This is the file that you'd want to include in a separate project 4:44 that has all functionality in, blog.js is the right file. 4:48 There are no tests. 4:54 You shouldn't really be publishing software with no tests, but 4:56 this is basic enough to get away with it. 4:59 I can add tests later on. 5:02 I can add my github reaper for this project. 5:06 And then there's the keywords for this project. 5:10 This is to help the npm search facility. 5:13 Treehouse, blog, rss and json make sense. 5:15 Author, Andrew Chalkley. 5:23 And finally the license. 5:28 It's impossible for people who are using your software to know how they can use it. 5:31 I'm going to use the MIT license because that's what's popular with FrailMax and 5:36 libraries like J Query and Rebiemwells. 5:40 This looks good. 5:43 And that's the hard bit over when you create the package.jsn file, 5:45 you're basically getting your package ready for distribution. 5:49 Let's see if we've got everything set up correctly before publishing. 5:53 I am going to go one folder up. 5:57 And create a new directory called package_test. 6:02 This is where I am going to test that the package is working correctly. 6:10 Let's create a file example.js. 6:16 And then, copy and paste the basic usage from the README into the example.js. 6:22 Now to install the package in the project folder. 6:44 Npm install has a usage where you can install from a folder. 6:49 Just type, npm install. 6:53 And then the path to your 6:57 package. 6:58 As you can see there's a node_modules folder now with treehouse_blog installed. 7:12 Let's type node example .js, and 7:18 see if it prints out the latest blog articles with the information. 7:23 Yes, and it does. 7:28 Finally, let's go back to our treehouse_blog folder. 7:30 We can now use the npm's publish command. 7:39 And that's it. 7:44 We can go to npmjs.com now and search for treehouse_blog. 7:45 And there it is. 7:57 Now anyone can install this npm package by using npm install treehouse_blog. 7:58 With your projects don't forget to commit this source code to GitHub so 8:04 others can see it and contribute to your project. 8:08 And if there are any issues they can file them there. 8:11