Skip to content

Commit

Permalink
docs: clearer (#5)
Browse files Browse the repository at this point in the history
<!-- 👋 Hi, thanks for sending a PR to ado-npm-auth-lite! 💖.
Please fill out all fields below and make sure each item is true and [x]
checked.
Otherwise we may not be able to review your PR. -->

## PR Checklist

- [x] Addresses an existing open issue: fixes #4 
- [ ] That issue was marked as [`status: accepting
prs`](https://github.com/johnnyreilly/ado-npm-auth-lite/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [ ] Steps in
[CONTRIBUTING.md](https://github.com/johnnyreilly/ado-npm-auth-lite/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

<!-- Description of what is changed and how the code change does that.
-->
Clarifies the documentation
  • Loading branch information
johnnyreilly authored Nov 8, 2024
1 parent 1d3a93c commit dfb7e59
Showing 1 changed file with 23 additions and 10 deletions.
33 changes: 23 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,34 +12,47 @@

## Usage

You know that you need to create a user `.npmrc` file if you encounter the following message when you try to `npm i`:
To get `ado-npm-auth-lite` to create the necessary user `.npmrc` file, run the following command:

```sh
```shell
npx --yes ado-npm-auth-lite --config .npmrc
```

Should you encounter the following message when you try to `npm i`:

```shell
npm error code E401
npm error Unable to authenticate, your authentication token seems to be invalid.
npm error To correct this please try logging in again with:
npm error npm login
```

To get `ado-npm-auth-lite` to create the necessary user `.npmrc` file on your behalf, run the following command:
That means either:

```shell
npx --yes ado-npm-auth-lite --config .npmrc
```
- You have no user `.npmrc` file **OR**
- The token in your user `.npmrc` file is out of date

This requires that you are authenticated with Azure. To authenticate, run `az login`. [Follow these instructions to install the Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli). The `az login` command will prompt you to log in to Azure, so that a token may be acquired by `ado-npm-auth-lite`. It is not necessary to run `az login` if you are already authenticated with Azure.
In either case, running `ado-npm-auth-lite` should resolve the issue.

Typically `ado-npm-auth-lite` will be used as part of a `preinstall` script in your `package.json`:
`ado-npm-auth-lite` requires that you are authenticated with Azure to acquire an Azure DevOps Personal Access Token. To authenticate, run `az login`. [If you need to install the Azure CLI, follow these instructions](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli). It is not necessary to run `az login` if you are already authenticated with Azure.

A great way to use `ado-npm-auth-lite` is as part of a `preinstall` script in your `package.json`:

```json
"scripts": {
"preinstall": "npx --yes ado-npm-auth-lite"
},
```

`ado-npm-auth-lite` detects whether it is running in a CI environment and does not create a users `.npmrc` file in that situation. It uses the [ci-info](https://github.com/watson/ci-info) library to achieve this.
`ado-npm-auth-lite` detects whether it is running in a CI environment and does **not** create a user `.npmrc` file in that case.

`ado-npm-auth-lite` requires the project `.npmrc` file exists in order that it can acquire the information to run. There is an optional `config` parameter; if it is not supplied `ado-npm-auth-lite` will default to use the `.npmrc` in the current project directory. There will be information in your Azure DevOps Artifacts section for connecting to the npm feed around creating a project `.npmrc`. The file will look something like this:

The `config` parameter is optional, and if not supplied will default to the `.npmrc` in the project directory. Crucially, `ado-npm-auth-lite` requires the project `.npmrc` file exists in order that it can acquire the information to run.
```shell
registry=https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/

always-auth=true
```

## Why Azure DevOps npm auth-lite?

Expand Down

0 comments on commit dfb7e59

Please sign in to comment.