npm package: @linschin/demo-npm-library
Description: Demonstration npm library package
Author: Linus Chin
Latest version: 1.0.4

# 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](https://www.totaltypescript.com/how-to-create-an-npm-package)
  - [How to Develop and Test NPM Package/Library/Module locally](https://medium.com/@mohandere/npm-packaging-for-local-development-1d79c38b1897)

*Project generated by* [project-scaffolder-ts](https://github.com/linschin/project-scaffolder-ts)


# Table of Contents
- [Installation](#installation)
- [Local Development of an npm Library](#Local Development of an npm Library)
  - [npm link](#npm-link) Strategy
  - [npm pack](#npm-pack) Strategy
- [Testing](#Testing)
- [Publishing](#Publishing)


# Installation
```bash
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](#npm-link)
2. [npm pack](#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/<package> 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**
```bash
cd demo-npm-library
npm link
```

### 2. **Add the library package to your project folder**
```bash
cd <project-folder>
npm link demo-npm-library
```

Note: To link multiple local libraries, execute npm link in a single command
```bash
npm link demo-npm-library another-library
```

### 3. **Use the library in the project**
```typescript
// 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**
```bash
# 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.
```bash
cd demo-npm-library
npm run localpack
```

### 2. **Install the tarball in the project folder**
```bash
cd <project-folder>
npm install ../demo-npm-library/dist/demo-npm-library-1.0.0.tgz
```

### 3. **Use the library in the project**
```typescript
// 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**
```bash
# 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](https://vitest.dev/). 
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](https://github.com/changesets/changesets/tree/main) 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.
   ```bash
   # 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**: 
   ```bash
   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:
```bash
npm login
```