Creating an npm package with TypeScript

Creating an npm package with TypeScript

Creating an npm package can be an exciting venture, as it allows you to share your code with other developers worldwide. By using TypeScript, you not only make your code more maintainable but also provide helpful type information to your package consumers. In this guide, we’ll walk through creating a simple npm package written in TypeScript that adds two numbers.

Prerequisites

1. Ensure you have Node.js and npm installed. If not, download and install them from the Node.js official website.
2. Basic knowledge of TypeScript and npm.

Step-by-Step Guide

1. Initialize the Project

Create a new directory for your project and navigate to it:

mkdir adder-ts
cd adder-ts

Initialize a new npm project:

npm init -y

This command creates a package.json file with default values.

2. Set Up TypeScript

Install TypeScript and @types/node (which provides TypeScript definitions for Node.js):

npm install typescript @types/node --save-dev

Now, initialize a TypeScript configuration:

npx tsc --init

This command creates a tsconfig.json file with default TypeScript configurations.

3. Write the TypeScript Code

In your project directory, create a file named index.ts. This will be the main file of your package.

export function add(x: number, y: number): number {
    return x + y;
}

4. Configure the Build Process

In your tsconfig.json, you can configure the output directory for your compiled JavaScript. For example:

{
  "compilerOptions": {
    ...
    "outDir": "./dist",
    ...
  },
  ...
}

Update your package.json to include a build script

{
  ...
  "scripts": {
    "build": "tsc"
  },
  ...
}

5. Prepare for Publishing

Before publishing, you should determine the entry point for your library. In package.json, set the main field to the compiled version of your code and types to the type definitions:

{
  ...
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  ...
}

6. Publishing to npm

Before publishing, ensure you’re logged in to npm:

npm login

Once logged in, build your TypeScript code

npm run build

Now, you can publish your package:

npm publish

7. Using the Package

After publishing, anyone can install and use your package:

npm install adder-ts

And in their TypeScript (or JavaScript) code:

import { add } from 'adder-ts';

console.log(add(2, 3)); // Outputs: 5

Adding Custom Names and Scopes

1. Creating a Scope on npm

Before publishing a package under a custom scope, you need to have an npm account, and the scope must be associated with your account.

For example:@nicks-adding-func Is your desired scope, you need to add your own.

you need to:

1. Sign up on npmjs.com if you haven’t already.
2. Log in to the npm CLI:

npm login

1. Create an organization (which will be used as your scope):

npm org create @nicks-adding-func

2. Naming Your Package

In your package.jsonThe name field should reflect your custom scope and desired package name:

{
  "name": "@nicks-adding-func/cli",
  ...
}

3. Publishing Under the Scope

By default, scoped packages are private. If you want to publish a public scoped package, you’ll need to specify it when publishing:

npm publish --access public

4. Installing Scoped Packages

Installing scoped packages is similar to regular packages. Users will need to include the full scope:

npm install @nicks-adding-func/cli

5. Benefits of Scoped Packages

• Avoid Name Collisions: With millions of packages on npm, the name you want might already be taken. Scoping gives you more freedom in naming.
• Branding and Trust: Especially for organizations, having an official scope can assure users that they are using the official package and not a fork or imitation.
• Clearer Semantics: Scopes can provide additional context. For example, a user might infer that @nicks-adding-func/cli is the official CLI tool for the nicks-adding-func project.

Conclusion

Creating an npm package with TypeScript is straightforward. TypeScript enhances the developer experience by adding type safety, and with the steps above, you can easily share your TypeScript libraries with the world. Happy coding!