As TypeScript grows in popularity, many developers are creating statically typed packages to take advantage of the benefits the language offers. In this post, we will cover the process of creating and publishing an NPM package using TypeScript.

1. Configuring the Environment

Make sure you have Node.js, NPM, and TypeScript installed. You can install TypeScript globally with:

npm install -g typescript

Check that everything is installed correctly:

node -v
npm -v
tsc -v

2. Creating the Project

Start by creating a directory for your project:

mkdir meu-pacote-typescript
cd meu-pacote-typescript

Initialize a Node.js project:

npm init

This will create the package.json file where you can define the basic package information.

3. Configuring TypeScript

Now, initialize a TypeScript project:

tsc --init

This will create a tsconfig.json file. Edit it as needed, but a common setting is as follows:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "declaration": true,
    "outDir": "./dist",
    "strict": true
  },
  "include": ["src/**/*"]
}

Here, we are configuring the TypeScript compiler to generate ES6 code, with CommonJS modules, and include type declarations (declaration: true). The compiled code will be placed in the dist.

4. Writing the Code

Create a src directory and inside it a file index.ts:

mkdir src
touch src/index.ts

In the index.ts file, write your package code. Let's create a simple function to convert strings to uppercase:

export function toUpperCase(str: string): string {
  return str.toUpperCase();
}

5. Compiling the Code

Compile TypeScript to JavaScript:

tsc

This will generate the JavaScript files and type declarations in the dist directory.

6. Testing the Package Locally

To test your package, you can install it locally in another project:

1. In your test project directory, run:

   npm install ../caminho-para-o-diretorio-do-seu-pacote/dist

1. Use the function in the test project:

   import { toUpperCase } from 'nome-do-seu-pacote';

   console.log(toUpperCase('hello world')); // "HELLO WORLD"

This ensures that both JavaScript code and type declarations work correctly.

7. Publishing on NPM

If everything is working correctly, you are ready to publish your package.

1. NPM Login

If you don't already have an NPM account, create one and log in:

   npm login

1. Publication

Before publishing, add a build script to package.json:

   "scripts": {
     "build": "tsc"
   }

And add the output path in package.json:

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

Now compile and publish:

   npm run build
   npm publish

If the package name already exists, you will need to choose a new name.

8. Updating the Package

To publish a new version, change the version in package.json, run npm run build again, and publish:

npm publish

9. Best Practices

• Documentation: Include a README.md file explaining how to use your package.
• Tests: Write tests using frameworks like Jest to ensure code works as expected.
• Linting: Use tools like ESLint and Prettier to maintain code quality.
• Versioning: Follow SemVer to version your package.

Conclusion

Creating and publishing TypeScript packages on NPM not only improves code quality, it also provides typing benefits to those consuming your package. By following this guide, you'll be ready to share your solutions with the JavaScript and TypeScript community, contributing to a stronger, more robust development ecosystem.

Now that you know the process, how about starting to build your next TypeScript package?