https://www.notion.so/Lab-create-npm-packages-cdebf3fd535f460da8f3832b0aa07b32

In this tutorial we will create a utility package called slugger that can turn any blog post title into url friendly slug: e.g: https://myblog.com/june/this-is-a-slugged-blog-post-title

Written by: Ajar ~ Yariv Gilad

Our Mission 🎯

To get oriented with the multi-layered workflow of npm package creation. Consider this as 'hello world' npm package :-)

Let’s begin:

1 - First - take care of the necessary accounts

• Make sure you have an active (free) account on npmjs.com and github.com. Please login to both.

2 - Set up a node.js project in VS Code

• On your Desktop - create a ‘workspace’ folder for all of our example projects today if you haven’t already.
• Inside your workspace, create a new folder named slugger for our first example project and open it in VS Code.
• Open the terminal (view → terminal, or right-click a file/folder in VS Code files tab and choose ‘open in Terminal’ )
• Run npm init -y --scope=@your_npm_username (npm init -y [email protected]) Notice we’re scoping the npm package to your npm username. Inspect the name field ****of your package in package.json
• Next - create a src folder just to keep things tidy and create an index.js file in it.
• In your package.json, update the main field to src/index.js This will direct npm to use this file as the main entry script file once slugger will be installed and used somewhere.

3 - login to npm in your terminal

• Login to npm using your terminal. Run either **npm login** or **npm adduser** You will be prompt to enter your npm username, password and a public visible email.
• You’re supposed to get an approval message once the login was successful. In case you’re not sure, you can always run npm whoami to check your npm login status.

4 - write some code

• In src/index.js - create a function called slugger that accepts any number of strings as arguments and returns a single string with hyphens between each word like so:  i-am-a-slugged-string-i-contain-no-spaces

5 - Create a consumer

• While developing, it would make sense to create another file that will use the slugger as if we've installed it and are using it.

• Create another file under the src folder called consumer.draft.js

• At this point, let’s install @ajar/marker dependency to log the results out to the console: **npm i @ajar/marker**

• install nodemon as well as a dev-dependency: **npm i -D nodemon**

• Add a dev script to package json to run our draft using nodemon:

  "scripts": { "dev": "nodemon src/consumer.draft.js" }

• In your src/consumer.draft.js write some code that requires the index.js module, where the slugger function exists. require @ajar/marker and print to the console the input string passed to the slugger and the output result to see it works.

• Run your dev script npm run dev

6 - Publish your package to npm public registry

• The first publish of a package to npm public registry requires explicit flag telling npm we want to make this package access a public one since we're using scoping which is also used in organisations writing private packages. in your terminal run npm publish --access=public You will notice the npm cli packaging your project files as a tgz and uploading it to the public registry

Congrats 🎉🎉🎉 You've created your first npm public package :) Try to create another project' install your new package from npm and use it.

7 - Add version control to your package

• In this tutorial we will be using the Conventional Commits convention which is a good habit to get into in any git supported project.
• In VS Code install an extension called Visual Studio Code Commitizen Support
• In your terminal, init your slugger project as a git repo git init
• Add a .gitignore file with at least node_modules mentioned in it.
• Add all files to the next commit git add .
• Next, instead of using git commit in your terminal, open the command panel ctrl + Shift + P /command + Shift + P and type Commitizen: conventional commit
• This will open a small wizard to guide you through the commit convention. Choose the type of your commit, ignore the scope, type a short message saying 'initial commit' and click enter for all the rest for now.
• After commiting, check the repo status with **git status**
• If all went well - add your github repo as a remote repo git remote add origin GITHUB-REPO-URL push to github git push origin master
• Add a README.md file and go through the process again... **git add .** ctrl + Shift + P then choose Commitizen to start the commit process
• git push origin master

8 - Update your npm package version

• Assuming all went well so far, let's update the package version on npm using the cli and republishing it.
• In your terminal run **npm version minor** notice the version field in your package.json was updated to reflect a new minor version. You can use npm version major , **npm version minor** or npm version patch to bump up the relevant version.
• After updating the version of your package run **npm publish** again to upload the updated version of your package to the npm public registry.
• Try updating your package in the other project that installed it and uses it.

9 - Add unit testing to your project

• While many testing tools exists out there, in this tutorial we will use Jest, so first let's install it: **npm i jest -D**

• in your src folder create another file and name it index.spec.js

• in your file, require your index.js module where slugger exist. and write a basic test code.

  /**

  • @describe [optional] - group of tests with a header to describe them / describe('testing slugger basic functionality', () => { /*
    • @it - unit tests can use the 'it' syntax / it('slugger can slug string with spaces', () => { ...your code here expect(input).toEqual(output); }) /*
    • @test - unit test can use the 'test' syntax */ test('slugger can slug any number of spacy strings', () => { ...your code here expect(inputs).toEqual(output); }) })

• Next, let's run those tests. In your package json add a test script

  "scripts": { "dev": "nodemon src/consumer.draft.js", "test": "jest ./src/index.spec.js", "test:watch": "npm test -- --watch", "test:coverage": "npm test -- --coverage" }

• You can examine the full vocabulary of jest expect here

10 - Next steps

• Learn how to enrich your README.md file, it makes it so much more enjoyable :) add badges and images or other elements to make your readme stand out while welcoming visitors to your package on npm.
• Finally, this step is completely optional - as Tibetan monks are accustomed to wash their rich mandala creations to the ocean, let's unpublish our work from the public npm registry: **npm unpublish —force**