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
• Installing npm packages from a CodeCatalyst package repository
• Installing npm packages from npmjs through CodeCatalyst
• Publishing npm packages to your CodeCatalyst package repository
• npm command support
  • Supported commands that interact with a package repository
  • Supported client-side 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.

To connect npm to your CodeCatalyst package repository

1. Open the CodeCatalyst console at https://codecatalyst.aws/.

2. Navigate to your project.

3. In the navigation pane, choose Packages.

4. Choose your package repository from the list.

5. Choose Connect to repository.

6. In Configuration details, in Package manager client, choose npm client.

7. Choose your operating system to view the corresponding configuration steps.

8. 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.

   2. Choose Create token.

   3. 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.

9. 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_name with your CodeCatalyst space name.

   • Replace proj_name with your CodeCatalyst project name.

   • Replace repo_name 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, 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 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.

2. 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 and choosing the npm-public-registry-gateway repository.

3. 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.

Publishing npm packages to your CodeCatalyst package repository

After you have completed Configuring npm with CodeCatalyst, 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 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 client-side 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	Guesses the location of a package’s bug tracker URL, and then it attempts to open it.
ci	Installs a project with a clean slate.
deprecate	Deprecates a version of a package.
dist-tag	Modifies package distribution tags.
docs	Guesses the location of a package’s documentation URL, and then it attempts to open it by using the --browser config parameter.
doctor	Runs a set of checks to validate that your npm installation can manage your JavaScript packages.
install	Installs a package.
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	Installs package and runs tests. Runs an npm install, followed immediately by an npm test.
outdated	Checks the configured registry to determine if any installed packages are outdated.
ping	Pings the configured or given npm registry and verifies authentication.
publish	Publishes a package version to the registry.
update	Guesses the location of a package’s repository URL, and then it attempts to open it by using the --browser config parameter.
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)	Displays the npm bin directory.
build	Builds a package.
cache	Manipulates the packages cache.
completion	Enables tab completion in all npm commands.
config	Updates the contents of the user and global npmrc files.
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	Edits an installed package. Selects a dependency in the current working directory and opens the package directory in the default editor.
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	Gets help on npm.
help-search	Searches npm help documentation.
init	Creates a package.json file.
link	Symlinks a package directory.
ls	Lists installed packages.
pack	Creates a tarball from a package.
prefix	Displays a prefix. This is the closest parent directory to contain a package.json file, unless -g is also specified.
prune	Removes packages that are not listed on the parent package's dependencies list.
rebuild	Runs the npm build command on the matched folders.
restart	Runs a package's stop, restart, and start scripts and associated pre-scripts and post-scripts.
root	Prints the effective node_modules directory to standard out.
run-script	Runs arbitrary package scripts.
shrinkwrap	Locks down dependency versions for publication.
uninstall	Uninstalls a package.

Unsupported commands

These npm commands are not supported by CodeCatalyst package repositories.

Command	Description	Notes
access	Sets the access level on published packages.	CodeCatalyst uses a permission model that is different from the public npmjs repository.
adduser	Adds a registry user account	CodeCatalyst uses a user model that is different from the public npmjs repository.
audit	Runs a security audit.	CodeCatalyst does not currently vend security vulnerability data.
hook	Manages npm hooks, including adding, removing, listing, and updating.	CodeCatalyst does not currently support any change notification mechanism.
login	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.
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	Manages package owners.	CodeCatalyst uses a permissions model that is different from the public npmjs repository.
profile	Changes settings on your registry profile.	CodeCatalyst uses a user model that is different from the public npmjs repository.
search	Searches the registry for packages matching the search terms.	CodeCatalyst does not support the search command.
star	Marks your favorite packages.	CodeCatalyst currently does not support any favorites mechanism.
stars	Views packages marked as favorites.	CodeCatalyst currently does not support any favorites mechanism.
team	Manages teams and team memberships.	CodeCatalyst uses a user and group membership model that is different from the public npmjs repository.
token	Manages your authentication tokens.	CodeCatalyst uses a different model for getting authentication tokens. For information, see Configuring npm with CodeCatalyst.
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	Displays the npm user name.	CodeCatalyst uses a user model that is different from the public npmjs repository.