This article focuses on how to create NuGet packages for your own JavaScript open source libraries that you might want to make public.
What is NuGet?
From the definition at the official site
NuGet is a Visual Studio extension that makes it easy to add, remove, and update libraries and tools in Visual Studio projects that use the .NET Framework
Essentially it’s an easy way to discover, deploy and manage dependencies in Visual Studio. They are similar to Ruby gems and very distant cousins of rpm packages (only for Visual Studio not OS level deployments). The extension helps you cleanly install and uninstall dependencies like NUnit, Ninject, log4Net or any other useful library that has been published as NuGet package on the NuGet gallery.
The unit of deployment in NuGet is referred to as a package. NuGet Gallery at www.nuget.org is the place to publish your final package if you want it available to all Visual Studio users.
In Visual Studio you install packages using the Package Manager Console.
This article focuses on how to create NuGet packages for your own JavaScript open source libraries that you might want to make public. Having said that, you can create packages to deploy binary dlls as well, we are leaving that out for another day.
Pre-Requisites
The NuGet package spec is an xml file that can be hand-coded too. However in this article, we will use the excellent NuGet Package Explorer utility that’s available on Codeplex. (As suggested by Iouri in the comments section, the updated link is npe.codeplex.com)It is a ClickOnce application and once deployed will check for updates when it starts and update itself, once done.
Decide on the License scheme for your distributable. In this tutorial, we will be packaging the Apache licensed google-diff-match-patch JavaScript implementation. I have taken written permission from Neil Fraser, the author of the library.
Creating the Package
Start NuGet Package Explorer and select ‘Create a new package (Ctrl+N)’.
A default set of values will be shown
Hit Ctrl+K or select Edit > Edit Package Metadata option on the menu to customize the package information.
Some of the fields are rather obvious. I’ll explain the implications of some of them below. Fields that are mandatory are in bold on-screen.
Id (Mandatory)– This is the name by which devs will be installing it. So to install the above package you have to say
Install-package Google.DiffMatchPatch.Js
No spaces and special characters allowed in this field.
Version (Mandatory) – If this is your library, following the naming conventions you usually do and map this value to the version of code you are going to package.
Title – A descriptive name of the package
Authors (Mandatory) – This is the package Author usually. Since I am packaging on Neil’s behalf I have made it clear.
Owner – Owner of the code
Icon – If you have a nice icon available for your package the url that goes here
Project Url – URL where the project is hosted or where more information can be obtained about the project.
Requires License Agreement – If you wish explicit license agreement check this. This will publish a license warning when the package is deployed from the console.
Summary – A summary of what the package is about.
Description (Mandatory) – Detailed description of what the package is about.
Release Notes – If any.
Scroll down for the rest of the parameters
Copyright – You can put in a separate copyright notice here if you want
Language – A Unicode Language name selection
Tags – Tags that will identify the package. Tags are space separated
Dependencies – If you are building a JavaScript library that is dependent of say another JavaScript library like jQuery, you could easily add it by adding the dependency. Click on the ‘Properties’ button to bring up the Package Selector
Click OK to add the package. In the current example we don’t need any dependencies.
At this point the package details are ready, but the actual content is missing. In the Package Contents column, right click and add select ‘Add Content Folder’. You can also drag and drop your code and let the Explorer infer the type of content and add it to the correct folder.
Content folder matches the root of the project to which the package is being added. For MVC Web projects, the JavaScript is traditionally placed under the ‘Scripts’ folder. So create a ‘Scripts’ folder under content (Right Click > Add New Folder).
Now add the files to the scripts folder.
All set, save the package. Choose a folder carefully such that you can use it to store other packages that you create. Later we will see how this helps create our own private ‘Nuget gallery’.
Testing your Nuget Package
Now that your package is ready, you have to test that everything works good. Fire up Visual Studio 2010 and go to the Tools > Library Package Manager > Package Manager Settings
This will bring up the Options dialog with Package Manager > General selected. Select ‘Package Sources’ node. You will see the default NuGet official package source as selected. Give a Name like ‘My Nuget Package Cloud’ and click on the ellipses button to select the folder where you saved your Nuget package. Click Add.
The Available Package Sources pane should look similar to the following
Hit OK to continue. Now go to the Package Manager Console and pull down the Package Source dropdown on top. Notice the source folder you added is coming up now. Select your custom source.
Type in ‘install-package’ and hit tab. Notice how it gets auto-completed. Hit enter to test the package installation. I got the following:
The required scripts would now be available in the Scripts folder. Notice how it implicitly makes you accept the license agreement (because you checked ‘Requires License Agreement’). The implicit license notice will not come up if you don’t select it.
Let’s see if uninstall works. Type in uninstall-package <package name> and hit enter. If you have not changed anything in the scripts that were installed by the package, it will leave them alone, else it will remove them.
Deploying the Package to Nuget.org
Once you have packaged your goodies you can make it available in the Nuget.org gallery.
Deploying to Nuget.org is a simple process. Create an account at Nuget.org to get your API Key. Once logged in to your account click on your user id on top right corner to get to your account details. There will be a big blue box at the bottom of the page, click on it to reveal your API key. Copy this key.
Now open the NuGet Package Explorer and open your package. Go to File > Publish (or Ctrl+P). Paste the API key copied earlier in the Publish key box. This is unique to you don’t share it with others. Uncheck the ‘Use the v1 protocol for this url. (This is for people maintaining previous version of nuget galleries in their own corporate environments).
Hit publish.
If all goes well, you’ll see a dialog like above (API/Publish key obfuscated) and there you have it.
Your magical creation is available for everyone to enjoy.
The Nuget package created in this tutorial is actually now published. You can get the diff-patch-match javascript implementation from Nuget gallery through package manager in Visual studio!
In Conclusion
Nuget is a great way to distribute open source projects. Instead of people coming to your site downloading, adding to projects, managing versions, they can just do an install from their package manager console and be done with it. Single step install and single step uninstall.
Nuget packages can do much more than shown in this simple example. Some of the things are:
-
If you have a big IT shop that shares dependencies amongst each other, hosting a custom nuget gallery is a great option.
-
You can pull in other file dependencies or binary dependencies if required into your own package
-
You can integrate the package building process with your own build process so that it generates an appropriate package every build and avoid all the manual steps above.
Hope you have fun with Nuget and publish all your cool libraries as nuget packages for everyone!
This article has been editorially reviewed by Suprotim Agarwal.
C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.
We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).
Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.
Click here to Explore the Table of Contents or Download Sample Chapters!
Was this article worth reading? Share it with fellow developers too. Thanks!
Sumit is a .NET consultant and has been working on Microsoft Technologies since his college days. He edits, he codes and he manages content when at work. C# is his first love, but he is often seen flirting with Java and Objective C. You can follow him on twitter at @
sumitkm or email him at sumitkm [at] gmail