Example TypeScript Package ready to be published on npm for 2021

This is an example TypeScript Package ready to be published on npm. It has been set up with automated tests and package publishing workflow using GitHub Actions CI/CD. It is made primarily for GitHub + VS Code (Windows / Mac / Linux) users who are about to write and publish their first TypeScript npm package. This package could serve as a starter / boilerplate / demo for them.

It uses npm, TypeScript compiler, Jest, webpack, ESLint, Prettier.

The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.

Development

You need to have Node.js installed. Node includes npm as its default package manager.

Open the whole package folder with a good code editor, preferably Visual Studio Code. Consider installing VS Code extensions ES Lint and Prettier.

In the VS Code top menu: Terminal -> New Terminal

Install dependencies

Install dependencies with npm:

npm i

Write your code

Make necessary changes in package.json (name, version, description, keywords, author, homepage and other URLs).

Write your code in src folder, and unit test in test folder, replacing the original files there.

The VS Code shortcuts for formatting of a code file are: Shift + Alt + F (Windows); Shift + Option (Alt) + F (MacOS); Ctrl + Shift + I (Linux).

Change code linting and formatting settings in .prettierrc.js if you want.

Test

Test your code with Jest framework:

npm run test

Build

Build production (distribution) files in your dist folder:

npm run build

It generates CommonJS (in dist/cjs folder), ES Modules (in dist/esm folder), bundled and minified UMD (in dist/umd folder), as well as TypeScript declaration files (in dist/types folder).

Try it before publishing

Run:

npm link

npm link will create a symlink in the global folder, which may be {prefix}/lib/node_modules/example-typescript-package or C:\Users<username>\AppData\Roaming\npm\node_modules\example-typescript-package.

Create an empty folder elsewhere, you don't even need to npm init (to generate package.json). Open the folder with VS Code, open a terminal and just run:

npm link example-typescript-package

This will create a symbolic link from globally-installed example-typescript-package to node_modules/ of the current folder.

You can then create a, for example, testnum.ts file with the content:

import { Num } from 'example-typescript-package'
console.log(new Num(5).add(new Num(6)).val() === 11)

If you don't see any linting errors in VS Code, if you put your mouse cursor over Num and see its type, then it's all good.

Whenever you want to uninstall the globally-installed example-typescript-package and remove the symlink in the global folder, run:

npm uninstall example-typescript-package -g

Publish

Create an npm account.

Manual Publishing

Log in:

npm adduser

And publish:

npm publish

CI Publishing

This package is configured to use GitHub Actions CI/CD to automate the npm publishing process. The following are what you have to do.

Follow npm's official instruction to create an npm token. Choose "Publish" from the website, or use npm token create without argument with the CLI.

If you use 2FA, then make sure it's enabled for authorization only instead of authorization and publishing (Edit Profile -> Modify 2FA).

On the page of your newly created or existing GitHub repo, click Settings -> Secrets -> New repository secret, the Name should be NPM_TOKEN and the Value should be your npm token.

Notes

• It uses npm but you can easily switch to yarn, of course (remember to change all "npm" in scripts in the file package.json)
  • Whether you use npm as your package manager ≠ Whether you can publish to the npm registry
• Works fine in VS Code. In my configuration .eslintrc and .prettierrc cooperate perfectly
• See scripts.build in package.json for other predefined script commands

References

• Creating and publishing unscoped public packages - npm docs
• npm-publish - npm docs
• Publishing - TypeScript docs
• Publishing Node.js packages - GitHub Docs

Btw, if you want to publish Python package, go to Example PyPI (Python Package Index) Package & Tutorial / Instruction / Workflow for 2021.