Building and Publishing NPM TypeScript Package : A Guide from Scratch

In this guide we will build NPM Package from scratch using TypeScript and publish it to the central repository as NPM Package. We will use TypeScript to write the package and Jest to test our code functionality.

What are We going to Build :-

This is what we are going to build , We are going to build a small soap web client package and publish in npm.

https://www.npmjs.com/package/soap-web-client

What is NPM :-

NPM is a package manager and world’s largest library for the node packages from where you could use open-source package and publish your package there. .

Let me tell you npm is a node based package manager . Its is used to manage your projects packages from online registry of packages public and private both . For developers npm is a command line tool , used to manage or pull packages often referred as project dependencies . If you are from a Java programming background , you can think of npm similar to maven .

Here is the official documentation of npm .

Why TypeScript ?

Typescript is a static typed language and helps you write error free code. Typescript is a superset of JavaScript which provides a richer environment for spotting common errors while you write the code.

Let’s KickOff :

Make sure to have latest version of the node, at least >= 7.6 because we have used async/await in our package which was introduced in the nodejs 7.6

Pick a Unique Name :
Since there are a number of packages available in npm, it will be hard for you to name your package but you’ll have to choose one. In this guide we have chosen the name “soap-web-client” since we are going to make a package for the soap web services.

Basic Setup :–

Make a Git Repository with the name you have chosen in https://github.com

Clone the created repository :- 

git clone <repository_name.git> && cd soap-web-client


Init your Package :

Let’s create the package.json file first. Enter the below command in command line.

npm init 

Or 

yarn init


Awesome we have done the basics. Package.json will look like something, not exactly. But for sure this package.json provides a metadata about our package that we are going to publish in npm .

npm install --save-dev typescript

Or 
yarn add -D typescript
Good now you’ll see the node_modules folder.
In order to compile typescript we also needed the tsconfig.json file. So let’s add the same in the root.

{
   "compilerOptions": {
       "target": "es5", /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */
       "module": "commonjs",
       "allowJs": true, /* Allow javascript files to be compiled. */
       "strict": true, /* Enable all strict type-checking options. */
       "outDir": "./lib", /* Redirect output structure to the directory. */
       "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */
   },
   "include": ["src"],
   "exclude": ["node_modules"]
}

Wooh, we have done lots of thing here, let’s understand , tsconfig file indicates the project as typescript project and it includes options on how the typescript files to be compiled

Browsers can’t execute TypeScript directly. Typescript must be “transpiled” into JavaScript using the tsc compiler, which requires some configuration. Typically, you add a TypeScript configuration file called tsconfig.json to your project to guide the compiler as it generates JavaScript files.

target – we want to compile down to “es5” whatever we are writing in the typescript file. There are other target options available.

module – Use commonjs for compatibility.

allowJs – allow javascript files to be compiled.

strict – enable all strict type checking options.

outDir – Redirect target to what directory.

include – which folder should we include for the typescript to be compile.

exclude – which folder should we exclude for the transpile.

Your first step to publish your own npm package :–
You are very close to publishing your first npm package. Let’s create the “src” folder and inside this let’s create “index.ts”.

Write any function inside the index.ts file and export that method.

const demoMethod = () => {
return “I’m Duffer”;
}
module.exports = demoMethod;

We have created soap-web-client service hence we have coded like that –

Okay now it is good to go, Next step is to add build scripts in the package.json under scripts.

“build” : “tsc”

Now run the build command in the terminal/console.

yarn build

Or 

npm run build

And Magic… You’ll see the lib folder in the root directory.

We have Created the our method which will be exported, let’s write a test case for the same using Jest.

Setup Testing with Jest :

Jest, an awesome package by Facebook.

Since we will be writing tests against our typescript source-files, we also need to add ts-jest and @types/jest. The test suite is only used during development so let’s add them as devDependencies.

npm install --save-dev jest ts-jest @types/jest

Or

yarn add -D jest ts-jest @types/jest


We have added the jest dependency now, let’s put the configuration for the test environment, you could put it into package.json or you could create some configuration file which will provide the configuration to test environment and same we will indicate in the package.json

Let’s create the new file  “jestconfig.json”.

and remove the old test script present in the package.json with

   "test": "jest --config=jestconfig.json",

We will add two more scripts inside the package.json for future use, one is to get code coverage and another is just to clean node_modules.

“coverage” :  “jest --config=jestconfig.json --coverage”,

“clean” : “sudo rm -rf node_modules/”
Now at the end package.json will look like this, you could add dependency on package.json what you need for the first package, but let’s make it simple.

We have done a test setup, let’s create __tests__ folder in the root directory to write the test case in one place.

Write a basic test case :

Let’s write a basic test case for the method we have written in the index.test.ts file.

const testDemoMethod = require(“../src/index”);
test(‘DemoTestCase’ , ()=>{
	expect(testDemoMethod()).toBe(`I’m Duffer`);
});

Save it, now try to run

npm test

Or

yarn test


You’ll see a screen like this, in-case some test are failing, resolve first.

Now we are ready to publish the first package – 

Commit your code to git :

git add .

git commit -m “my first package”

git push origin master

If you don’t have an account at npm, first create the account at https://www.npmjs.com/signupIf you have command then let’s login first in our terminal.

npm login

Or 

yarn login

Provide your username and email id of registered npmjs account, you’ll not have to put your password here.

Last step towards magic :

Let’s publish it, now run publish and provide credentials of npmjs account.

npm publish


Or 

yarn publish


View your package – 
Now you could browse your package at npm. The url of the package will be https://npmjs.com/pacakge/<your-package-name>, in my case it is https://www.npmjs.com/package/soap-web-client

Nice we have got a new package …

Bumping a new version :

If you have made changes and want to push it again after the latest changes then let’s add patch version.

npm version patch


Or 

yarn version --patch


And then again Publish it using the publish command.

Happy coding and publishing ….

Connect with us at LinkedIn –

Yogesh Joshi