1 | # libnpmpublish
|
2 |
|
3 | [![npm version](https://img.shields.io/npm/v/libnpmpublish.svg)](https://npm.im/libnpmpublish)
|
4 | [![license](https://img.shields.io/npm/l/libnpmpublish.svg)](https://npm.im/libnpmpublish)
|
5 | [![CI - libnpmpublish](https://github.com/npm/cli/actions/workflows/ci-libnpmpublish.yml/badge.svg)](https://github.com/npm/cli/actions/workflows/ci-libnpmpublish.yml)
|
6 |
|
7 | [`libnpmpublish`](https://github.com/npm/libnpmpublish) is a Node.js
|
8 | library for programmatically publishing and unpublishing npm packages. Give
|
9 | it a manifest as an object and a tarball as a Buffer, and it'll put them on
|
10 | the registry for you.
|
11 |
|
12 | ## Table of Contents
|
13 |
|
14 | * [Example](#example)
|
15 | * [Install](#install)
|
16 | * [API](#api)
|
17 | * [publish/unpublish opts](#opts)
|
18 | * [`publish()`](#publish)
|
19 | * [`unpublish()`](#unpublish)
|
20 |
|
21 | ## Example
|
22 |
|
23 | ```js
|
24 | const { publish, unpublish } = require('libnpmpublish')
|
25 | ```
|
26 |
|
27 | ## Install
|
28 |
|
29 | `$ npm install libnpmpublish`
|
30 |
|
31 | ### API
|
32 |
|
33 | #### <a name="opts"></a> `opts` for `libnpmpublish` commands
|
34 |
|
35 | `libnpmpublish` uses
|
36 | [`npm-registry-fetch`](https://npm.im/npm-registry-fetch). Most options
|
37 | are passed through directly to that library, so please refer to [its own
|
38 | `opts` documentation](http://npm.im/npm-registry-fetch#fetch-options) for
|
39 | options that can be passed in.
|
40 |
|
41 | A couple of options of note:
|
42 |
|
43 | * `opts.defaultTag` - registers the published package with the given tag,
|
44 | defaults to `latest`.
|
45 |
|
46 | * `opts.access` - tells the registry whether this package should be
|
47 | published as `public` or `restricted`. Only applies to scoped
|
48 | packages. Defaults to `public`.
|
49 |
|
50 | * `opts.token` - can be passed in and will be used as the authentication
|
51 | token for the registry. For other ways to pass in auth details, see the
|
52 | n-r-f docs.
|
53 |
|
54 | * `opts.provenance` - when running in a supported CI environment, will trigger
|
55 | the generation of a signed provenance statement to be published alongside
|
56 | the package. Mutually exclusive with the `provenanceFile` option.
|
57 |
|
58 | * `opts.provenanceFile` - specifies the path to an externally-generated
|
59 | provenance statement to be published alongside the package. Mutually
|
60 | exclusive with the `provenance` option. The specified file should be a
|
61 | [Sigstore Bundle](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto)
|
62 | containing a [DSSE](https://github.com/secure-systems-lab/dsse)-packaged
|
63 | provenance statement.
|
64 |
|
65 | #### <a name="publish"></a> `> libpub.publish(manifest, tarData, [opts]) -> Promise`
|
66 |
|
67 | Sends the package represented by the `manifest` and `tarData` to the
|
68 | configured registry.
|
69 |
|
70 | `manifest` should be the parsed `package.json` for the package being
|
71 | published (which can also be the manifest pulled from a packument, a git
|
72 | repo, tarball, etc.)
|
73 |
|
74 | `tarData` is a `Buffer` of the tarball being published.
|
75 |
|
76 | If `opts.npmVersion` is passed in, it will be used as the `_npmVersion`
|
77 | field in the outgoing packument. You may put your own user-agent string in
|
78 | there to identify your publishes.
|
79 |
|
80 | If `opts.algorithms` is passed in, it should be an array of hashing
|
81 | algorithms to generate `integrity` hashes for. The default is `['sha512']`,
|
82 | which means you end up with `dist.integrity = 'sha512-deadbeefbadc0ffee'`.
|
83 | Any algorithm supported by your current node version is allowed -- npm
|
84 | clients that do not support those algorithms will simply ignore the
|
85 | unsupported hashes.
|
86 |
|
87 | ##### Example
|
88 |
|
89 | ```js
|
90 | // note that pacote.manifest() and pacote.tarball() can also take
|
91 | // any spec that npm can install. a folder shown here, since that's
|
92 | // far and away the most common use case.
|
93 | const path = '/a/path/to/your/source/code'
|
94 | const pacote = require('pacote') // see: http://npm.im/pacote
|
95 | const manifest = await pacote.manifest(path)
|
96 | const tarData = await pacote.tarball(path)
|
97 | await libpub.publish(manifest, tarData, {
|
98 | npmVersion: 'my-pub-script@1.0.2',
|
99 | token: 'my-auth-token-here'
|
100 | }, opts)
|
101 | // Package has been published to the npm registry.
|
102 | ```
|
103 |
|
104 | #### <a name="unpublish"></a> `> libpub.unpublish(spec, [opts]) -> Promise`
|
105 |
|
106 | Unpublishes `spec` from the appropriate registry. The registry in question may
|
107 | have its own limitations on unpublishing.
|
108 |
|
109 | `spec` should be either a string, or a valid
|
110 | [`npm-package-arg`](https://npm.im/npm-package-arg) parsed spec object. For
|
111 | legacy compatibility reasons, only `tag` and `version` specs will work as
|
112 | expected. `range` specs will fail silently in most cases.
|
113 |
|
114 | ##### Example
|
115 |
|
116 | ```js
|
117 | await libpub.unpublish('lodash', { token: 'i-am-the-worst'})
|
118 | //
|
119 | // `lodash` has now been unpublished, along with all its versions
|
120 | ```
|