Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Using npm
These topics describe how you can use `npm`, the Node.js package manager, with CodeCatalyst.
**Note**
CodeCatalyst supports `node v4.9.1` and later and `npm v5.0.0` and later.
**Topics**
+ [Configuring and using npm](packages-npm-use.md)
+ [npm tag handling](packages-npm-tags.md)
# Configuring and using npm
To use `npm` with CodeCatalyst, you must connect `npm` to your package repository and provide a personal access token (PAT) for authentication. You can view instructions for connecting `npm` to your package repository in the CodeCatalyst console.
**Contents**
+ [Configuring npm with CodeCatalyst](#npm-configure)
+ [Installing npm packages from a CodeCatalyst package repository](#npm-install)
+ [Installing npm packages from npmjs through CodeCatalyst](#npm-install-npmjs)
+ [Publishing npm packages to your CodeCatalyst package repository](#npm-publish)
+ [npm command support](#npm-commands)
+ [Supported commands that interact with a package repository](#supported-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-client-side-commands)
+ [Unsupported commands](#unsupported-commands)
## Configuring npm with CodeCatalyst
The following instructions explain how to authenticate and connect `npm` to your CodeCatalyst package repository. For more information about npm, see the [official npm documentation](https://docs.npmjs.com/).
**To connect `npm` to your CodeCatalyst package repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to your project.
1. In the navigation pane, choose **Packages**.
1. Choose your package repository from the list.
1. Choose **Connect to repository**.
1. In **Configuration details**, in **Package manager client**, choose **npm client**.
1. Choose your operating system to view the corresponding configuration steps.
1. A personal access token (PAT) is required to authenticate npm with CodeCatalyst. If you already have a token, you can use it. If not, you can create one using the following steps.
1. **(Optional):** Update the **PAT name** and **Expiration date**.
1. Choose **Create token**.
1. Copy and store your PAT in a safe location.
**Warning**
You will not be able to see or copy your PAT again after you close the dialog box. Credentials should be short lived to minimize the length of time an attacker can use the credentials after misappropriating them.
1. Run the following commands from your project's root directory to configure npm with your package repository. The commands will do the following:
+ Create a project-level `.npmrc` file if your project does not have one.
+ Add the package repository endpoint information to your project-level `.npmrc` file.
+ Add your credentials (PAT) to your user-level `.npmrc` file.
Replace the following values.
**Note**
If you are copying from the console instructions, the values in the following commands are updated for you and do not need to be changed.
+ Replace *username* with your CodeCatalyst user name.
+ Replace *PAT* with your CodeCatalyst PAT.
+ Replace *space\$1name* with your CodeCatalyst space name.
+ Replace *proj\$1name* with your CodeCatalyst project name.
+ Replace *repo\$1name* with your CodeCatalyst package repository name.
```
npm set registry=https://packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/ --location project
npm set //packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/:_authToken=username:PAT
```
**For npm 6 or lower:** To make npm always pass the auth token to CodeCatalyst, even for `GET` requests, set the always-auth configuration variable with `npm config set` as follows.
```
npm set //packages.region.codecatalyst.aws/npm/space-name/proj-name/repo-name/:always-auth=true --location project
```
## Installing npm packages from a CodeCatalyst package repository
After you connect npm to your repository by following the steps in [Configuring npm with CodeCatalyst](#npm-configure), you can run `npm` commands on your repository.
You can install an npm package that is in your CodeCatalyst package repository or one of its upstream repositories with the `npm install` command.
```
npm install lodash
```
## Installing npm packages from npmjs through CodeCatalyst
You can install npm packages from [npmjs.com](https://www.npmjs.com/) through a CodeCatalyst repository by configuring the repository with an upstream connection to the gateway repository connected to npmjs.com, **npm-public-registry-gateway**. Packages installed from npmjs are ingested and stored in the gateway repository, and the farthest downstream package repository.
**To install packages from npmjs**
1. If you haven't already done so, configure `npm` with your CodeCatalyst package repository by following the steps in [Configuring npm with CodeCatalyst](#npm-configure).
1. Check that your repository has added the gateway repository, **npm-public-registry-gateway**, as an upstream connection. You can check which upstream sources are added or add **npm-public-registry-gateway** as an upstream source by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the **npm-public-registry-gateway** repository.
1. Install packages with the `npm install` command.
```
npm install package_name
```
For more information about requesting packages from upstream repositories, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).
## Publishing npm packages to your CodeCatalyst package repository
After you have completed [Configuring npm with CodeCatalyst](#npm-configure), you can run `npm` commands.
You can publish an npm package to a CodeCatalyst package repository with the `npm publish` command.
```
npm publish
```
For information about how to create npm packages, see [Creating Node.js Modules](https://docs.npmjs.com/getting-started/creating-node-modules) on *npm Docs*.
## npm command support
The following sections summarize the `npm` commands that are supported by CodeCatalyst package repositories, in addition to listing specific commands that are not supported.
**Topics**
+ [Supported commands that interact with a package repository](#supported-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-client-side-commands)
+ [Unsupported commands](#unsupported-commands)
### Supported commands that interact with a package repository
This section lists `npm` commands where the `npm` client makes one or more requests to the registry to which it is configured (for example, `npm config set registry`). These commands have been verified to function correctly when invoked against a CodeCatalyst package repository.
****
| Command | Description |
| --- | --- |
| [bugs](https://docs.npmjs.com/cli/bugs) | Guesses the location of a package’s bug tracker URL, and then it attempts to open it. |
| [ci](https://docs.npmjs.com/cli/ci) | Installs a project with a clean slate. |
| [deprecate](https://docs.npmjs.com/cli/deprecate) | Deprecates a version of a package. |
| [dist-tag](https://docs.npmjs.com/cli/dist-tag) | Modifies package distribution tags. |
| [docs](https://docs.npmjs.com/cli/docs) | Guesses the location of a package’s documentation URL, and then it attempts to open it by using the `--browser` config parameter. |
| [doctor](https://docs.npmjs.com/cli/doctor) | Runs a set of checks to validate that your npm installation can manage your JavaScript packages. |
| [install](https://docs.npmjs.com/cli/install) | Installs a package. |
| [install-ci-test](https://docs.npmjs.com/cli/install-ci-test) | Installs a project with a clean slate and runs tests. Alias: `npm cit`. This command runs an `npm ci`, followed immediately by an `npm test`. |
| [install-test](https://docs.npmjs.com/cli/install-test) | Installs package and runs tests. Runs an `npm install`, followed immediately by an `npm test`. |
| [outdated](https://docs.npmjs.com/cli/outdated) | Checks the configured registry to determine if any installed packages are outdated. |
| [ping](https://docs.npmjs.com/cli/ping) | Pings the configured or given npm registry and verifies authentication. |
| [publish](https://docs.npmjs.com/cli/publish) | Publishes a package version to the registry. |
| [update](https://docs.npmjs.com/cli/update) | Guesses the location of a package’s repository URL, and then it attempts to open it by using the `--browser` config parameter. |
| [view](https://docs.npmjs.com/cli/view) | Displays package metadata. Can also be used to print metadata properties. |
### Supported client-side commands
These commands don't require any direct interaction with a package repository, so CodeCatalyst does not require anything to support them.
****
| Command | Description |
| --- | --- |
| [bin (legacy)](https://docs.npmjs.com/cli/v8/commands/npm-bin) | Displays the npm `bin` directory. |
| [build](https://docs.npmjs.com/cli/v6/commands/npm-build) | Builds a package. |
| [cache](https://docs.npmjs.com/cli/cache) | Manipulates the packages cache. |
| [completion](https://docs.npmjs.com/cli/completion) | Enables tab completion in all npm commands. |
| [config](https://docs.npmjs.com/cli/config) | Updates the contents of the user and global `npmrc` files. |
| [dedupe](https://docs.npmjs.com/cli/dedupe) | Searches the local package tree and attempts to simplify the structure by moving dependencies further up the tree where they can be more effectively shared by multiple dependent packages. |
| [edit](https://docs.npmjs.com/cli/edit) | Edits an installed package. Selects a dependency in the current working directory and opens the package directory in the default editor. |
| [explore](https://docs.npmjs.com/cli/explore) | Browses an installed package. Spawns a subshell in the directory of the specified installed package. If a command is specified, then it is run in the subshell, which then immediately shuts down. |
| [help](https://docs.npmjs.com/cli/help) | Gets help on npm. |
| [help-search](https://docs.npmjs.com/cli/help-search) | Searches npm help documentation. |
| [init](https://docs.npmjs.com/cli/init) | Creates a `package.json` file. |
| [link](https://docs.npmjs.com/cli/link) | Symlinks a package directory. |
| [ls](https://docs.npmjs.com/cli/ls) | Lists installed packages. |
| [pack](https://docs.npmjs.com/cli/pack) | Creates a tarball from a package. |
| [prefix](https://docs.npmjs.com/cli/prefix) | Displays a prefix. This is the closest parent directory to contain a `package.json` file, unless `-g` is also specified. |
| [prune](https://docs.npmjs.com/cli/prune) | Removes packages that are not listed on the parent package's dependencies list. |
| [rebuild](https://docs.npmjs.com/cli/rebuild) | Runs the `npm build` command on the matched folders. |
| [restart](https://docs.npmjs.com/cli/restart) | Runs a package's stop, restart, and start scripts and associated pre-scripts and post-scripts. |
| [root](https://docs.npmjs.com/cli/root) | Prints the effective `node_modules` directory to standard out. |
| [run-script](https://docs.npmjs.com/cli/run-script) | Runs arbitrary package scripts. |
| [shrinkwrap](https://docs.npmjs.com/cli/shrinkwrap) | Locks down dependency versions for publication. |
| [uninstall](https://docs.npmjs.com/cli/uninstall) | Uninstalls a package. |
### Unsupported commands
These `npm` commands are not supported by CodeCatalyst package repositories.
****
| Command | Description | Notes |
| --- | --- | --- |
| [access](https://docs.npmjs.com/cli/access) | Sets the access level on published packages. | CodeCatalyst uses a permission model that is different from the public npmjs repository. |
| [adduser](https://docs.npmjs.com/cli/adduser) | Adds a registry user account | CodeCatalyst uses a user model that is different from the public npmjs repository. |
| [audit](https://docs.npmjs.com/cli/audit) | Runs a security audit. | CodeCatalyst does not currently vend security vulnerability data. |
| [hook](https://docs.npmjs.com/cli/v9/commands/npm-hook) | Manages npm hooks, including adding, removing, listing, and updating. | CodeCatalyst does not currently support any change notification mechanism. |
| [login](https://docs.npmjs.com/cli-commands/adduser.html) | Authenticates a user. This is an alias for `npm adduser`. | CodeCatalyst uses an authentication model that is different from the public npmjs repository. For information, see [Configuring npm with CodeCatalyst](#npm-configure). |
| [logout](https://docs.npmjs.com/cli/logout) | Signs out of the registry. | CodeCatalyst uses an authentication model that is different from the public npmjs repository. There is no way to sign out from a CodeCatalyst repository, but authentication tokens expire after their configurable expiration time. The default token duration is 12 hours. |
| [owner](https://docs.npmjs.com/cli/owner) | Manages package owners. | CodeCatalyst uses a permissions model that is different from the public npmjs repository. |
| [profile](https://docs.npmjs.com/cli/profile) | Changes settings on your registry profile. | CodeCatalyst uses a user model that is different from the public npmjs repository. |
| [search](https://docs.npmjs.com/cli/search) | Searches the registry for packages matching the search terms. | CodeCatalyst does not support the `search` command. |
| [star](https://docs.npmjs.com/cli/star) | Marks your favorite packages. | CodeCatalyst currently does not support any favorites mechanism. |
| [stars](https://docs.npmjs.com/cli/stars) | Views packages marked as favorites. | CodeCatalyst currently does not support any favorites mechanism. |
| [team](https://docs.npmjs.com/cli/team) | Manages teams and team memberships. | CodeCatalyst uses a user and group membership model that is different from the public npmjs repository. |
| [token](https://docs.npmjs.com/cli/token) | Manages your authentication tokens. | CodeCatalyst uses a different model for getting authentication tokens. For information, see [Configuring npm with CodeCatalyst](#npm-configure). |
| [unpublish](https://docs.npmjs.com/cli/unpublish) | Removes a package from the registry. | CodeCatalyst does not support removing a package version from a repository by using the npm client. You can delete a package in the console. |
| [whoami](https://docs.npmjs.com/cli/whoami) | Displays the npm user name. | CodeCatalyst uses a user model that is different from the public npmjs repository. |
# npm tag handling
npm registries support *tags*, which are string aliases for package versions. You can use tags to provide an alias instead of using version numbers. For example, you have a project with multiple streams of development and you use a different tag for each stream (for example, `stable`, `beta`, `dev`, `canary`). For more information, see [dist-tag](https://docs.npmjs.com/cli/dist-tag) on *npm Docs*.
By default, npm uses the `latest` tag to identify the current version of a package. `npm install pkg` (without `@version` or `@tag` specifier) installs the latest tag. Typically, projects only use the latest tag for stable release versions. Other tags are used for unstable or prerelease versions.
## Editing tags with the npm client
The three `npm dist-tag` commands (`add`, `rm`, and `ls`) function the same way in CodeCatalyst package repositories as they function in the [default npm registry](https://registry.npmjs.com/).
## npm tags and upstream repositories
When `npm` requests the tags for a package and versions of that package are also present in an upstream repository, CodeCatalyst merges the tags before returning them to the client. For example, a repository named `R` has an upstream repository named `U`. The following table shows the tags for a package named `web-helper` that's present in both repositories.
****
| Repository | Package name | Package tags |
| --- | --- | --- |
| R | `web-helper` | *latest* (alias for version 1.0.0) |
| U | `web-helper` | *alpha* (alias for version 1.0.1) |
In this case, when the npm client fetches the tags for the `web-helper` package from repository `R`, it receives both the *latest* and *alpha* tags. The versions the tags point to won't change.
When the same tag is present on the same package in both the upstream and local repository, CodeCatalyst uses the tag that was *last updated*. For example, suppose that the tags on *webhelper* have been modified to look like the following.
****
| Repository | Package name | Package tags | Last updated |
| --- | --- | --- | --- |
| R | `web-helper` | *latest* (alias for version 1.0.0) | January 1, 2023 |
| U | `web-helper` | *latest* (alias for version 1.0.1) | June 1, 2023 |
In this case, when the npm client fetches the tags for package *web-helper* from repository `R`, the *latest* tag will alias the version *1.0.1* because it was updated last. This makes it easy to consume new package versions in an upstream repository that are not yet present in a local repository by running `npm update`.