Create and publish an npm library, with TypeScript and Semantic Versioning

Remi Guan — Fri, 13 Sep 2024 05:45:15 +0000

🚀 Write and publish a minimal code

To publish a library on npm, you'll need:

A npm account; you can sign up here.
Your code as a project; i.e., you have a package.json in your code directory, which has name and version specified. Note that you can generate this file via:

npm init

An index.js in your project. Remember, you need to export your function to allow users to import it.

Note: If your script isn't named index.js and placed in the project root, you need to specify the "main" property in package.json. See this answer for more info.

And if the name has been taken on npm, you can add a prefix like @name-or-org/your-lib; that's what most other libraries do nowadays.

You can check my minimal example for reference, but I believe you can write something cooler than this.

Finally, publish it with the CLI command:

npm publish

Note to people setting the package name with a prefix: It MUST be your npm username or organization name you registered on npm. For example, I can use @remi_guan as my prefix but not others.

Also, you need to run npm publish --access public, because npm thinks you want to publish a private package, which is a paid feature.

This output means it has been successful. However, if you ran into some trouble, you can search on Google to troubleshoot. And here's how you can use your own library:

If you've been following this guide, please try your own library instead.

I've also found @backendbro has a much detailed guide than this, if you would like to know more.

After you have published your code, when you want to update the code, can run npm publish again. However, before publish you should update the version property of package.json, and please comply with Semantic Versioning.

I suggest you try it! Can you publish your library's v1.0.1 or v1.1.0, and use it in another project like what I've just done? Can you figure out how to update your npm library's version?

💖 Use TypeScript

This library we've created so far is not modern, it lacks type declaration so people who use your library can't get highlighted with typing. Also, people commonly use TypeScript with ECMAScript syntax. To learn about the difference: Node.js Modules: CommonJS vs. ECMAScript by Saisathish

But I'm going to skip the detailed setup of TypeScript in this post. There are many good tutorials to learn how to initialize a TypeScript project, like “How to develop a Typescript Library” by inapeace0.

Even further, you can use a template TypeScript repository like alexjoverm/typescript-library-starter that has already integrated many modern tools, best practices, etc.

I'm just going to mention some important notes if you're publishing a TypeScript library:

Build before you publish. If you need to publish it to the public, people with the most common Node.js environment can only execute .js files. So you need to compile your code with tsc, rollup (or vite, which uses rollup), or webpack; any one is okay.

You need to correctly point to the compiled file by using module, main, or entry properties in package.json. Using a template and learning them one by one is a good choice. Again, alexjoverm/typescript-library-starter specified them nicely.

Include a .d.ts file. For the same reason, the user also needs access to the type signatures.

But if you're sure your library will run on Deno, Bun, or ts-node, you can ignore my above guidelines because they support running TypeScript code natively.

Please try to follow a guide to create a TypeScript library and publish it to npm. It's still easy, like the first example. You should test it with another project using import syntax, and you can see type hints with an IDE.

With TypeScript, I can write my library in this syntax:

And after publishing, I can install and import it, and see the type hints thanks to TypeScript.

✨ Semantic Versioning

There's a common but slightly advanced problem waiting to be solved: Each time we update our package, we need to edit the version code.

That's annoying, especially if you're frequently updating your code.

However, there are tools to help you out.

semantic-release: Fully automatic; you can integrate it into GitHub CI to automatically update the version code and publish to npm each time you update your code on GitHub.
release-it: Also helps you bump the version, but it's simple to use (no need for CI knowledge); meanwhile, you don't configure it as fully automated.

I used ChatGPT to generate this summary comparing the two tools. For new coders, I'd suggest you try release-it, but semantic-release is also convenient if you know how to integrate it with CI.

In this post I'm going to show you how to use release-it, well, after you have made change to the project, simply run this in your project:

npx release-it

And choose is it a minor change or major change, then you're done!

Summary

So there you have it! We've walked through publishing a simple npm library, updating it, and even using TypeScript to make it more modern and robust. Remember to:

Export your functions properly so others can use them.
Update your version numbers following Semantic Versioning.
Consider using TypeScript for better type safety and developer experience.
Automate your releases with tools like release-it or semantic-release to save time.

Give it a try! Publish your own library, update it, and see how it feels to contribute to the npm ecosystem. Happy coding!

Forem: Remi Guan

Create and publish an npm library, with TypeScript and Semantic Versioning

🚀 Write and publish a minimal code

💖 Use TypeScript

✨ Semantic Versioning

Summary