From db4494c28c61fae0889a9519e0bd35ccc8bdbea5 Mon Sep 17 00:00:00 2001 From: johnnyreilly Date: Sun, 8 Dec 2024 06:33:30 +0000 Subject: [PATCH] fix: edits --- .../index.md | 4 +- .../index.md | 72 +++++++++++-------- 2 files changed, 46 insertions(+), 30 deletions(-) diff --git a/blog-website/blog/2024-11-09-introducing-azdo-npm-auth/index.md b/blog-website/blog/2024-11-09-introducing-azdo-npm-auth/index.md index 44f5b3d8b4c..4b38a3c0c38 100644 --- a/blog-website/blog/2024-11-09-introducing-azdo-npm-auth/index.md +++ b/blog-website/blog/2024-11-09-introducing-azdo-npm-auth/index.md @@ -1,6 +1,6 @@ --- slug: introducing-azdo-npm-auth -title: 'Introducing Azure DevOps npm auth' +title: 'Introducing azdo-npm-auth (Azure DevOps npm auth)' authors: johnnyreilly tags: [azure devops, node.js] image: ./title-image.png @@ -12,7 +12,7 @@ Azure DevOps has a feature called Azure Artifacts that supports publishing npm p ![title image reading "Introducing Azure DevOps npm auth" with an Azure DevOps and npm logos](title-image.png) -[Azure DevOps npm auth](https://github.com/johnnyreilly/azdo-npm-auth) exists to ease the setting up of local authentication to Azure DevOps npm feeds, particularly for non Windows users. +[`azdo-npm-auth`](https://github.com/johnnyreilly/azdo-npm-auth) exists to ease the setting up of local authentication to Azure DevOps npm feeds, particularly for non Windows users. diff --git a/blog-website/blog/2024-12-07-npx-and-azure-artifacts-the-secret-cli-delivery-mechanism/index.md b/blog-website/blog/2024-12-07-npx-and-azure-artifacts-the-secret-cli-delivery-mechanism/index.md index 27996ff91ae..fc15756819f 100644 --- a/blog-website/blog/2024-12-07-npx-and-azure-artifacts-the-secret-cli-delivery-mechanism/index.md +++ b/blog-website/blog/2024-12-07-npx-and-azure-artifacts-the-secret-cli-delivery-mechanism/index.md @@ -8,7 +8,7 @@ hide_table_of_contents: false description: 'By combining npx and Azure Artifacts, you can deliver your command line application to consumers in a way that is easy to use and secure.' --- -The [`npx` command](https://docs.npmjs.com/cli/v8/commands/npx) is a powerful tool for running CLI tools shipped as npm packages, without having to install them globally. If you have a private npm feed, you can use `npx` to run your CLI tool from that feed. +The [`npx` command](https://docs.npmjs.com/cli/v8/commands/npx) is a powerful tool for running CLI tools shipped as npm packages, without having to install them globally. It's typically used to run packages on the public npm registry. However, if you have a private npm feed, you can also use `npx` to run packages available on that feed. Azure Artifacts is a feature of Azure DevOps that supports publishing npm packages to a feed for consumption. By combining `npx` and Azure Artifacts, you can deliver your CLI tool to consumers in a way that's easy to use and secure. @@ -22,55 +22,53 @@ This post shows how to use `npx` and Azure Artifacts to deliver your private CLI If you've ever found a need to deliver a private CLI tool to consumers, you'll know that it can be a challenge. -I work for a large organization and we need to share internal tools with our colleagues. The problem is, that it's hard to get people to install and update the tools. Either you need to provide detailed instructions on how to install the tool, or you need to create an installer that people can run. You then have the subsequent problem of how to update the tool. +I work for a large organization and we need to share internal tools with our colleagues. The problem is, that it's hard to get people to install tools. Either you need to provide detailed instructions on how to install the tool, or you need to work out some kind of internal distribution mechanism. You also have to think about how to update the tool. It's not simple. -By combining `npx` and Azure Artifacts you no longer need to worry about any of that. You can publish your tool to a private npm feed and then consumers can run it with a single command. They don't need to install anything up front, and they don't need to worry about updates. +By combining `npx` and Azure Artifacts you no longer need to worry about any of that. You can publish your CLI tool to a private npm feed and then consumers can run it with a single command. They don't need to install anything up front (apart from Node.js which they likely already have), and they don't need to worry about updates. A typical usecase is the one I've mentioned; sharing tools internally in an organisation. But, broader than that, if you want to deliver a private npm package to consumers, this is a great way to do it. -We're going to look at how we'd achieve this with Azure Artifacts as the host of the npm package. But, you could use any npm feed that you have access to. +We're going to look at how we'd achieve this with Azure Artifacts as the host of the npm package. But, you could use any private npm feed that you have access to. -## How to combine `npx` with Azure Artifacts +## Publishing a package to Azure Artifacts Before you can use `npx` to run your CLI tool, you need to publish it to a private npm feed. Here is a guide on [how to publish a private npm package with Azure Artifacts](../2024-12-07-npx-and-azure-artifacts-the-secret-cli-delivery-mechanism/index.md). In that example we published a package to a feed called `npmrc-script-organization` in the `johnnyreilly` organization of Azure DevOps / Azure Artifacts. -For the sake of our example, we'll say that our package is a CLI tool with the name `@johnnyreilly/my-cli-tool`. An npm package which houses a CLI tool is merely a package with a [`bin` entry in the `package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin). This post is not about how to create a CLI tool, but rather how to deliver it to consumers. If you would like to see an example of what a CLI tool package looks like, you can check out the [`azdo-npm-auth` package on GitHub](https://github.com/johnnyreilly/azdo-npm-auth). +For the sake of our example, we'll say that our package is a CLI tool with the name `@johnnyreilly/my-cli-tool`. -The question now is, how we can run the `@johnnyreilly/my-cli-tool` package with `npx`? First, I want to be clear on the pieces of information that we need to know: +Remember, an npm package which houses a CLI tool is merely an npm package with a [`bin` entry in the `package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin). This post is not about how to create a CLI tool, but rather how to deliver one to private consumers. If you would like to see an example of what a CLI tool package looks like, you can check out the [`azdo-npm-auth` package on GitHub](https://github.com/johnnyreilly/azdo-npm-auth). (In fact, we'll use `azdo-npm-auth` later in this post - it's an example of a CLI tool published to the **public** npm registry.) -1. The name of the organization in Azure DevOps / Azure Artifacts. In our case, it's `johnnyreilly`. -2. The name of the feed in Azure DevOps / Azure Artifacts. In our case, it's `npmrc-script-organization`. -3. The name of the package. In our case, it's `@johnnyreilly/my-cli-tool`. +The question now is, how we can run the (private) `@johnnyreilly/my-cli-tool` package with `npx`? -All of the above will be different for you, so you'll need to replace these values with your own. +## The `registry` config setting of `npm` / `npx` -## The `registry` option of `npm` / `npx` +The secret sauce of running a CLI tool from a private npm feed with `npx` is the [`registry` config setting of `npm` / `npx`](https://docs.npmjs.com/cli/v8/using-npm/config#registry). The `registry` option allows you to specify the URL of the npm feed that you want to use. In our case, the URL is `https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/`. -The secret sauce of running a CLI tool from a private npm feed with `npx` is the [`registry` option of `npm` / `npx`](https://docs.npmjs.com/cli/v8/using-npm/config#registry). The `registry` option allows you to specify the URL of the npm feed that you want to use. In our case, the URL is `https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/`. - -We constructed this by combining the organization and the feed names above into the following format: - -`https://pkgs.dev.azure.com/[ORGANIZATION]/_packaging/[FEED]/npm/registry/` - -Even easier is just to grab it from the Azure DevOps UI by clicking on the "Connect to Feed" button in the Azure Artifacts section: +We grabbed the registry URL from the Azure DevOps UI by clicking on the "Connect to Feed" button in the Azure Artifacts section: ![Screenshot of "connect to feed" in Azure DevOps](screenshot-connect-to-feed.webp) -Then select `npm` and you'll see the instructions for setting up the `.npmrc` file: +When we selected `npm`, ADO displayed instructions for setting up an `.npmrc` file for private feed consumption: ![Screenshot of the instructions for setting up the `.npmrc` file](screenshot-npmrc.png) -You can see the registry URL in the `.npmrc` file above. +We don't need to set up an `.npmrc` file to run the CLI tool with `npx`, but we do need to grab the registry URL. ## Running the CLI tool with `npx` -Equipped with this information, we can now run our CLI tool with `npx`: +Equipped with the registry URL, we can now run our CLI tool with `npx`: ```shell npx -y --registry https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/ @johnnyreilly/my-cli-tool ``` -This command will download the `@johnnyreilly/my-cli-tool` package from the private npm feed and run it. The `--registry` option tells `npx` to use the specified registry to download the package. +This command will download the `@johnnyreilly/my-cli-tool` package from the private npm feed and run it. The `--registry` option tells `npx` to use the specified registry URL to download the package and the `-y` option tells `npx` to answer "yes" to the installation prompt. + +If you need to pass arguments to the CLI tool, you can simply add them to the end of the command as you would with any CLI tool: + +```shell +npx -y --registry https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/ @johnnyreilly/my-cli-tool --arg1 hello +``` There is another way to specify the registry URL, which is to use the `npm_config_registry` environment variable. This approach is more verbose and is not cross platform (it won't work on Windows). But, if you prefer this approach, you can use this style of command: @@ -89,19 +87,37 @@ npm error To correct this please try logging in again with: npm error npm login ``` -Then you probably need a new token. You can get a new token by running [`azdo-npm-auth`](https://github.com/johnnyreilly/azdo-npm-auth) (the package I created to help with this problem). You can run it like this: +Then npm is telling you to authenticate with the npm feed. This is because the feed is private and requires authentication. This is a good thing; it means that your package is secure; just as you'd hoped. + +You may have your own way of authenticating with the feed. If so, great! Do that now and skip the next section. + +## Using `azdo-npm-auth` to authenticate with Azure Artifacts + +On the other hand, if you're using Azure Artifacts ([and your Azure DevOps organisation is connected with your Azure account / Microsoft Entra ID](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/connect-organization-to-azure-ad?view=azure-devops)), you can use [`azdo-npm-auth`](https://github.com/johnnyreilly/azdo-npm-auth) to solve your authentication needs. You can run `azdo-npm-auth` like this: + +```shell +npx -y azdo-npm-auth --registry https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/ +``` + +The above command will acquire a PAT (Personal Access Token) from Azure DevOps and use it to create a user `.npmrc` file, which will be used by `npx` to authenticate with the feed subsequently. + +If you encounter a `npm error code E401` as you run the `azdo-npm-auth` command, it's possible that you have a local `.npmrc` file that is tripping `npx` up. You can get around that by explicitly passing the `--registry` of the public npm feed to `npx`: ```shell -npx -y --registry https://registry.npmjs.org azdo-npm-auth --organization johnnyreilly --feed npmrc-script-organization +npx -y --registry https://registry.npmjs.org azdo-npm-auth --registry https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/ ``` -This is assuming your feed is organization-scoped. If your feed is project-scoped, you will need to supply the `project` value: +That's right; we're passing the public npm feed to `npx`'s `--registry` and we're passing our private feed's registry URL to `azdo-npm-auth`'s `--registry`. This is a way to get around the `npm error code E401` issue. + +## Running the original command again + +Whichever way you authenticated, you should now be ready. You can now run the original command again; it should work this time. For example: ```shell -npx -y --registry https://registry.npmjs.org azdo-npm-auth --organization johnnyreilly --project my-project --feed project-feed-name +npx -y --registry https://pkgs.dev.azure.com/johnnyreilly/_packaging/npmrc-script-organization/npm/registry/ @johnnyreilly/my-cli-tool ``` -Then you can run the original command again; it should work this time. +And that's it! You've successfully run your CLI tool from a private npm feed with `npx`. ## Conclusion