What is NPM Package ?

working with javascript/typescript; sometime we create some utility methods or useful code snippet which we copy in our several projects, here some npm package handy.

in this post we will create a very basic npm package and test and publish it, earlier it was in javascript but later added typescript.

Pre-requisite

create an account on npmjs website, ite free.
enable 2FA so it would be comfortable while publishing the package.
a local project which is based on npm and with typescript support, where you can test and verify before publish the package.
a IDE ( preferably, VS code editor)
Typescript ( npm i typescript -g will add it globally)

lets’ start

create new folder ( in my case, its npm/demo ) and navigate it from terminal and run

> npm init

this will ask few questions and when finished , it will generate a package.json file in your folder, alternatively you can run npm init --yes also

Tip: create a scoped package (i.e. name starts with @ ) so that will be unique,

added few necessary scripts, you can copy it from below

"scripts": {
  "build": "npx tsc",
  "prepublishOnly": "npm run build"
}

package.json

{
  "name": "@xkeshav/day",
  "version": "1.3.0",
  "description": "A npm package which return milliseconds in one day.",
  "main": "./lib/index.js",
  "types": "./lib/index.d.ts",
  "repository": {
    "type": "github",
    "url": "https://github.com/<username>/<project_name.git>"
  },
  "homepage": "https://github.com/<username>/<project_name.git>",
  "scripts": {
    "build": "npx tsc",
    "prepublishOnly": "npm run build",
    "publish": "npm publish --access=public"
  },
  "keywords": ["day", "typescript", "javascript", "xkeshav"],
  "files": ["./lib/**"],
  "author": "Keshav Mohta<@xkeshav>",
  "license": "MIT",
  "devDependencies": {
    "typescript": "^5.3.3"
  }
}

here important properties are files, name and main

files will contain files, which will be downloaded when someone do npm install your package
name is the name of package which is used to indicate when someone do npm install, in my case here it will be npm install @xkeshav/day
we are using typescript so main and types will be there and there file location will be from lib folder

create tsconfig.json file

> tsc -- init

it will generate default tsconfig.json, you can remove many of rules. below is my tsconfig.json file content

tsconfig.json

{
  "compilerOptions": {
    "incremental": true,
    "target": "es5",
    "module": "commonjs",
    "declaration": true,
    "outDir": "./lib",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Note: here outDir will be same as files in package.json

now create src/index.ts file and add your own code which you want to include in the package, use export keyword; below is the content of file

export const oneDay = 5 ** 5 * 4 ** 4 * 3 ** 3 * 2 ** 2 * 1 ** 1;

here in my package , named export a constant.

build the package before publish and check the code in lib folder

> npm run build

How to test locally?

before publish , if you want to verify whether our package will work as expected or not then we can test with 2 approach

npm link way

after the build, run below command on same folder

> npm link

now go to another project (which is npm based and typescript supported ) and run below

> npm link @xkeshav/day

and now in any typescript file write

import { oneDay } from @xkeshav/day

console.log({oneDay});

you are good to check. if you find any issue in your package; then run

> npm unlink @xkeshav/day

and do changes in your main package and again run npm link and follow the same.

npm pack approach

go to your project where custom npm package is, and run

> npm pack

which will output looks like this

npm notice
npm notice package: @xkeshav/day@1.3.0
npm notice === Tarball Contents ===
npm notice 1.1kB LICENSE
npm notice 493B  README.md
npm notice 37B   lib/index.d.ts
npm notice 203B  lib/index.js
npm notice 713B  package.json
npm notice === Tarball Details ===
npm notice name:          @xkeshav/day
npm notice version:       1.3.0
npm notice filename:      xkeshav-day-1.3.0.tgz
npm notice package size:  1.5 kB
npm notice unpacked size: 2.5 kB
npm notice shasum:        4abcdefghijklmnopqrstuvwxyz6
npm notice integrity:     sha512-xyz==
npm notice total files:   5
npm notice
xkeshav-day-1.3.0.tgz

after executing this command successfully, a tar.gz file will be created the same folder, copy this file and paste it in another project you want to use it.

now navigate to the another project root in terminal and run

> npm install xkeshav-day-1.3.0.tgz

above command will add entry of the package in the package.json file as below

  "dependencies": {
    "@xkeshav/day": "file:xkeshav-day-1.3.0.tgz"
  }

and now you can use the same way

import { oneDay } from @xkeshav/day


console.log({oneDay});

if something went wrong while building the package, then do npm uninstall xkeshav-day-1.3.0.tgz and fix the issue in the package and repeat the same process to install again.

Publish

now once you verified your package locally, its time to publish, for that

make sure you are logged in to your npm account prior to run below command

now go to your npm package project root and run

> npm publish --access=public

this command will pause on one place and asked to Enter and when you hit Enter, it will open npm OTP page in the browser and that page will ask to enter OTP ( if 2FA enabled ) and then after few seconds it will publish the package and you will the information on terminal

alternatively you can add this command in package.json script ( shown in earlier code snippet )and run npm run publish

Update the version of package

if you want to update your package then

either update the version value in the package.json

"version": "1.7.5"

or run

> npm version <patch|minor|major>

which automatically update version;

side note: minor will update second number by +1; patch will increase the third place number by +1 and major will update first place number one by + 1

where to see package on npm

Thanks.

How to create NPM package without bundler