@grinvald.alexander/slugger NPM

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

Our Mission 🎯

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

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

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 --scope=@grinvald.alexander) 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.

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.

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

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

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.

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

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.

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

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**

5 years ago

5 years ago