Hello, users! π
Today I'll be explaining (in an easy format) how to create and publish a npm package, no matter if it is for your styles or your logic.
I wanted to create this tutorial after the release of my first npm package ππ₯³, you can see it here.
Let's do this, let's create your npm packageπ.
π£. Create your account
I'm not joking, you need an account in npm, register your user here.
π£. Create your npm source folder & your package.json
Go to your desktop, create a new folder, name it npm_yourname_test for example (or the name of your future package).
Open this folder in your terminal. First of all, type
npm init
then, some questions will appear.
1. Name your package
// NAME OF YOUR PACKAGE
package name: (test)
Type your package name. For this example, I used 'npm_desire_test', use a specific name since things like "test", "test1" and etc are probably taken. The result is as follows:
// NAME OF YOUR PACKAGE
package name: (test) npm_desire_test
2. Version of your package
Set the default version (1.0.0).
// VERSION OF YOUR PACKAGE
version: (1.0.0) 1.0.0
3. The description of your package
Create a short description of your package.
// DESCRIPTION OF YOUR PACKAGE
description: A test package for npm.
4. The entry point of your package
Basically, we're talking about in which file your styles/logic will be placed. By default it's set to index.js, however this may cause conflicts with other index.js that the user has in its own project.
If you're using npm to create a logic package, (javaScript), create an entry point using the".js" extension. For example: util_functions.js.
If you're using npm to create a styles package (css, sass, css, stylus), create an entry point using the ".scs", ".sass", ".css" (etc.) extension. For example: myCardStyles.scss.
For this example I'll type test.js.
// ENTRY POINT (WHERE YOUR CODE WILL BE)
entry point: (index.js) test.js
5. The test command for your package
A test command for your package. (I actually don't use this, but oh well).
// A COMMAND TEST
test command: test
6. The Git repo for your project
The URL of the Git repo where your project is being kept.
For this example, I'm not using any, so I'll type "none".
// GIT REPO
git repository: none
7. Keywords
The keywords for your package. Use commas between them.
// YOUR KEYWORDS
keywords: your, keywords, for, the, package
8. The author of the package
Your name or the author's name.
// YOUR NAME
author: your name here
9. The package's license
There are plenty of licenses around the internet. Check the licenses here and the SPDX code for the license you want here.
I'll pick a random license for the example.
// SEARCH FOR A CORRECT SPDX LICENSE NAME
license: (ISC) CC-BY-ND-4.0
10. Checking the results
After finishing the initialization, the console will prompt your answers in a JSON. If everything's correct, go ahead.
π£ Creating the entry point
Remember your entry point? The one where your logic/styles must be placed?
Open the folder where you just created the package.json for your npm package in Visual Studio or your favorite IDE.
Create the file for your entry point with the same name you wrote in the package.json.
In the case for this example, it was test.js.
Inside, create your code or styles.
Code example:
// test.js
function alertThis(){
alert('Alert from my npm package')
}
Styles example:
// test.css
.myOwnStyle {
color: lightblue;
font-weight: bold;
}
Styles example but with sass/scss:
// test.scss
.otherStyle {
color: lightblue;
font-weight: bold;
}
π£ Creating your readme
Important.
Your package needs a file named readme.md, this readme is similar to Github's readme and etc., you can write it in markdown.
Your readme should contain some basics: what's your package about, info about you, how to install it, how to set it up in someone's code...
## What is this about? π€
Something!
## How to install this package?
...
Once you've created what you needed, it's time to publish your npm package! π₯³
π£ Publish your npm package
Finally, time for it to see the light!
Let's go back to the console where the folder of your npm package is open.
First of all, you must login to npm through your console.
Type
npm login
It'll ask your username, password and email, and will let you know once you're connected to npm.
Now, it's time: publish your package with the command
npm publish
If it gives you an error:
- Maybe you're not logged in correctly. Close the console and try to log in and publish it again.
- Your package name is probably taken, go to package.json, and change it.
π£ Install it and try it
Now it's time to set up how your package can be used in a project.
*You can also test it before publishing it, as you want.
Create a new project, (with or without a js framework), and check all the ways you can use and import your package.
It is important that you document in your package readme how to set up the package, or else anyone will understand how to use your package.
Here some examples (of projects where I'm not using any js framework):
Importing my test.js function
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<!-- MY PACKAGE IMPORTED AS A JS FILE π -->
<script src="node_modules/npm_desire_test/test.js"></script>
</head>
<body>
<!-- MY PACKAGE FUNCTION INSIDE THE HTML π -->
<button onclick="alertThis()">alerta</button>
</body>
</html>
Importing my test.css styles
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
<!-- MY PACKAGE IMPORTED AS CSS π -->
<link rel="stylesheet" href="node_modules/npm_desire_test/test.css">
</head>
<body>
<!-- MY CLASS IMPORTED USED IN AN H2 π -->
<h2 class="myOwnStyle">
Title affected by the styles in my npm
</h2>
</body>
</html>
If your package is made with preprocessors like sass or scss, make sure to try out how to set it up and running and document it in your readme.md so everyone (and yourself in +5 months after the last time you used your own package), know what to do to use your package.
π£ Uploading a new version of your package
Whenever you change, improve or modify your package, you must again open the folder in your console, log into npm (in the console, as before) and type the command:
npm version patch
before using again
npm publish
to upload the next/new/improved/modified/etc version of your package.
π£ Deleting your package
If you'd like to delete your package, open the package folder in your terminal, log in (in the console), and type
npm unpublish
if it doesn't let you unpublish it, use
npm unpublish --force
instead.
π£ In conclusion
That's it for now!
I hope this was useful and you could create, test and publish your own npm package. π₯³
Let's keep coding π»!