Publishing Packages

Important Note

This guide covers setting up a publishable package from scratch. A quick start for publishable packages is available through @rootreeweb/quick-start

Prerequisites

The package name is scoped correctly (starts with @rootreeweb/**) and is unique.
- Note that you must re-run yarn install after changing the package name in package.json to ensure that the package is installed correctly.
You have authenticated with the registry. To do this, run
```
npm login --scope=@rootreeweb --auth-type=legacy --registry=https://npm.pkg.github.com
```
Provide it with a Personal Access Token (Classic) that has access to write:packages. See Using Our Private Packages for more details on access tokens if necessary.

Initial Publishing Configuration

Specify the repository’s publishing configuration in package.json with:
```
{
	"publishConfig": {
		"{Your user name}:registry": "https://npm.pkg.github.com"
	}
}
```
Otherwise, the package will be published to the public NPM registry, and not the GitHub registry that we use for private packages.
Ensure that
```
"private": true
```
is NOT present in the package.json file. This will prevent the package from being published to any registry.
Ensure that the main field in package.json is set to the correct entry point for the package. This is typically dist/index.js for JavaScript packages.
```
"main": "dist/index.js"
```
Ensure that the files field in package.json is set to the correct files to be included in the package. This is typically dist/ for JavaScript packages.
```
"files": [
	"dist/"
]
```
Ensure that the scripts field in package.json includes a build script that will build the package. This is typically tsc for TypeScript packages:
```
"scripts": {
	...other scripts...
	"build": "tsc"
}
```
In the scripts field, add a ‘release’ script that will run the build script and then publish the package. This is typically the following:
```
"scripts": {
...other scripts...
	"release": "yarn build && npm publish"
}
```
(Note: do not name the script publish. This will cause the package to attempt to publish twice each time it is run.)
Ensure that the version field in package.json exists and is set to the correct version number. This is typically 0.0.0 for new packages.
```
"version": "0.0.0"
```

Publishing (Or Updating an Existing Package)

If someone else set up the existing configuration, ensure that the publishConfig in package.json includes your GitHub username. (Step 1 of the Initial Publishing Configuration).
Update the version number in package.json to the new version number. The version number should follow Semantic Versioning. The registry will not allow you to publish a package with the same version number as an existing package. For example, if the current version is 1.0.0, the next version could be 1.0.1 for a patch, 1.1.0 for a minor, or 2.0.0 for a major.
Run the release script to build and publish the package:
```
yarn release
```
If the package is new, or if the version number was updated, the package will be published to the registry. If the version number was not updated, the package will not be published, and you will receive an error message.
Make sure to commit and push any changes that were made. Publishing will not update the repository, only the package.

Updating a Package in a Project

Either
```
yarn add @rootreeweb/{package-name}@{version}
```
Where {package-name} is the name of the package and {version} is the new version number to install.

Or alternatively:
```
yarn upgrade-interactive
```
To interactively upgrade any out-of-date packages in the project. This is typically the quicker and easier option. (Note that versions of Yarn before 4.0.0 require extra steps that are not covered here.)