demo-npm-library

Demonstration of a simple npm library. A reminder on how to create and use an npm library locally.

References:

• TotalTypescript - How To Create An NPM Package
• How to Develop and Test NPM Package/Library/Module locally

Project generated by project-scaffolder-ts

Table of Contents

• Installation
• [Local Development of an npm Library](#Local Development of an npm Library)
  • npm link Strategy
  • npm pack Strategy
• Testing
• Publishing

Installation

cd demo-npm-library
npm install
npm run ci

Local Development of an npm Library

When developing an npm library, you may want to test it locally before publishing it to the npm registry. This can be done by linking the library to a local project or by packing the library into a tarball and installing it in the project.

There are multiple methods to use an npm library locally.

1. npm link
2. npm pack

npm link

With this method, we create a symbolic link to the library package in the global node_modules folder, and then link it to the project folder's node_modules.

For more information about the npm link command, see npm help link.

npm-link - Symlink a package folder

This is handy for installing your own stuff, so that you can work on it and test iteratively without having to continually rebuild.

Package linking is a two-step process.

First, npm link in a package folder with no arguments will create a symlink in the global folder {prefix}/lib/node_modules/ that links to the package where the npm link command was executed. It will also link any bins in the package to {prefix}/bin/{name}. Note that npm link uses the global prefix (see npm prefix -g for its value).

Next, in some other location, npm link package-name will create a symbolic link from globally-installed package-name to node_modules/ of the current folder.

Note that package-name is taken from package.json, not from the directory name.

The package name can be optionally prefixed with a scope. See npm help scope. The scope must be preceded by an @-symbol and followed by a slash.

1. Link the library package to the global node_module folder

cd demo-npm-library
npm link

2. Add the library package to your project folder

cd <project-folder>
npm link demo-npm-library

Note: To link multiple local libraries, execute npm link in a single command

npm link demo-npm-library another-library

3. Use the library in the project

// index.ts
import { add, subtract } from 'demo-npm-library'
import { greet, farewell } from 'demo-npm-library'

console.log(add(1, 3))
console.log(subtract(5, 2))

console.log(greet('Linus'))
console.log(farewell('Linus'))

4. Clean up

# Remove linked library from the project
cd <project-folder>
npm unlink

# Remove linked library from the global node_module folder
npm ls --global
npm uninstall demo-npm-library

npm pack

With this method, we create a tarball of the library package and install it in the project folder.

For more information about the npm pack command, see npm help pack.

1. Create a tarball of the library package

Note: A pre-prepared script localpack is provided in the package.json file to create the tarball that is created in the dist folder.

cd demo-npm-library
npm run localpack

2. Install the tarball in the project folder

cd <project-folder>
npm install ../demo-npm-library/dist/demo-npm-library-1.0.0.tgz

3. Use the library in the project

// index.ts
import { add, subtract } from 'demo-npm-library'
import { greet, farewell } from 'demo-npm-library'

console.log(add(1, 3))
console.log(subtract(5, 2))

console.log(greet('Linus'))
console.log(farewell('Linus'))

4. Clean up

# Remove the installed package from the project
cd <project-folder>
npm uninstall demo-npm-library

There is no need to clean up the library folder since the tarball is created in the dist folder and does not affect the library package itself.

Testing

The library is tested using vitest. Test executed has been automatically baked into the npm run ci command.

There are two npm scripts provided for testing:

1. npm run test: Executes the tests (warning - build must be executed separately)
2. npm run dev: Starts the test runner in watch mode

Publishing

Publishing utilises the changesets npm library to manage versioning and changelogs. There is no automated publishing proceess through GitHub Actions.

In order to publish the library to the npm registry, you need to:

1. Create a changeset: This will create a new version of the library and update the changelog.

   # Starts an interactive prompt to determine the version bump type (major, minor, patch) 
   npx changeset

2. Create a changeset version and publish the library to the npm registry:

   npm run local-release

3. Commit the changeset files to your repository.

Pre-requisites

Ensure that you have a valid npm account and that you are logged in to the npm registry. You can log in using the following command:

npm login