Repository files navigation

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, husky, pinst, commitlint. The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.

(Click the above button to use this example package as a template for your new GitHub repo, this will initialize a new repository and my commits will not be in your git history)

(If you do not use GitHub, you candownload the archive of the example package)

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

Open the whole package folder with a good code editor, preferablyVisual Studio Code. Consider installing VS Code extensionsES Lint andPrettier.

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

Install dependencies with npm:

npm i

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

Write your code insrc folder, and unit test intest 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 your code with Jest framework:

npm runtest

Note: Example TypeScript Package useshusky,pinst andcommitlint to automatically execute test andlint commit message before every commit.

Build production (distribution) files in yourdist folder:

npm run build

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

Run:

npm link

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

Create an empty folder elsewhere, you don't even need tonpm init (to generatepackage.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 tonode_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(newNum(5).add(newNum(6)).val()===11)

If you don't see any linting errors in VS Code, if you put your mouse cursor overNum 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

Create annpm account.

npm adduser

npm publish

This package is configured to use GitHub Actions CI/CD to automate both thenpm andGitHub Packages publishing process. The following are what you have to do.

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

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

On the page of your newly created or existing GitHub repo, clickSettings ->Secrets ->New repository secret, theName should beNPM_TOKEN and theValue should be your npm token.

The default configuration of this example packageassumes you publish package with an unscoped name to npm. GitHub Packages must be named with a scope name such as "@tomchen/example-typescript-package".

Changescope: '@tomchen' to your own scope in.github/workflows/publish.yml, also changeaddscope inpackage.json.

If you publish package with a scoped name to npm, change the name to something like "@tomchen/example-typescript-package" inpackage.json, and remove the- run: npm run addscope line in.github/workflows/publish.yml

If you publish your package to npm only, and don't want to publish to GitHub Packages, then delete the lines from- name: Setup .npmrc file to publish to GitHub Packages to the end of the file in.github/workflows/publish.yml.

(You might have noticedsecret.GITHUB_TOKEN in.github/workflows/publish.yml. You don't need to set up a secret namedGITHUB_TOKEN actually, it isautomatically created)

Now everything is set. The example package has automated tests and upload (publishing) already set up with GitHub Actions:

• Every time yougit push or a pull request is submitted on yourmaster ormain branch, the package is automatically tested against the desired OS and Node.js versions with GitHub Actions.
• Every time anannotated (notlightweight) "v*" tag is pushed onto GitHub, a GitHub release is automatically generated from this version, it also automatically publishes to the npm registry and/or GitHub Packages registry to update the package there.
  • npm version /yarn version is useful to create tags.
  • (npm or yarn v1, not yarn v2) You could also add"postversion": "git push --follow-tags" topackage.json file to push it automatically afternpm oryarnversion.
  • (yarn v1, not v2) becauseyarn version doesn't check whether there are uncommitted changes, you can add"preversion": "git diff-index --quiet HEAD --" topackage.json
    • Note:preversion,postversion doesn't work in yarn v2

For npm registry: you can unpublish a version or the whole package but can never re-publish the same version under the same name.

If you want to modify the description / README on the npm package page, you have to publish a new version. You can modify the description on GitHub Packages without publishing.

• It uses npm but you can easily switch to yarn, of course (remember to change all "npm" inscripts in the filepackage.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
• Seescripts inpackage.json for other predefined script commands
• pinst is used to solvea problem of husky
• The installation of the package with npm, yarn v1 and yarn v2+ is ensured inthis test

• 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 toExample PyPI (Python Package Index) Package & Tutorial / Instruction / Workflow for 2021.