@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
dependabot/npm_and_yarn/main/proc-log-7.0.0
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 167 lines 6.72 KB
Raw
1 ---
2 title: Creating and publishing scoped public packages
3 ---
4
5 import shared from '~/shared.js'
6
7 To share your code publicly in a user or organization namespace, you can publish public user-scoped or organization-scoped packages to the npm registry.
8
9 For more information on scopes, see "[About scopes][scopes]".
10
11 <Note>
12
13 **Note:** Before you can publish user-scoped npm packages, you must [sign up](https://www.npmjs.com/signup) for an npm user account.
14
15 Additionally, to publish organization-scoped packages, you must [create an npm user account](https://www.npmjs.com/signup), then [create an npm organization](https://www.npmjs.com/signup?next=/org/create).
16
17 </Note>
18
19 ## Creating a scoped public package
20
21 1. If you are using npmrc to [manage accounts on multiple registries][reg-config], on the command line, switch to the appropriate profile:
22
23 ```
24 npmrc <profile-name>
25 ```
26
27 2. On the command line, create a directory for your package:
28
29 ```
30 mkdir my-test-package
31 ```
32
33 3. Navigate to the root directory of your package:
34
35 ```
36 cd my-test-package
37 ```
38
39 4. If you are using git to manage your package code, in the package root directory, run the following commands, replacing `git-remote-url` with the git remote URL for your package:
40
41 ```
42 git init
43 git remote add origin git://git-remote-url
44 ```
45
46 5. In the package root directory, run the `npm init` command and pass the scope to the `scope` flag:
47 - For an organization-scoped package, replace `my-org` with the name of your organization:
48
49 ```
50 npm init --scope=@my-org
51 ```
52
53 - For a user-scoped package, replace `my-username` with your username:
54 ```
55 npm init --scope=@my-username
56 ```
57
58 6. Respond to the prompts to generate a [`package.json`](https://docs.npmjs.com/about-package-json-and-package-lock-json-files) file. For help naming your package, see "[Package name guidelines][pkg-name]".
59 7. Create a [README file][readme-file] that explains what your package code is and how to use it.
60 8. In your preferred text editor, write the code for your package.
61
62 ## Reviewing package contents for sensitive or unnecessary information
63
64 Publishing sensitive information to the registry can harm your users, compromise your development infrastructure, be expensive to fix, and put you at risk of legal action. **We strongly recommend removing sensitive information, such as private keys, passwords, [personally identifiable information][pii] (PII), and credit card data before publishing your package to the registry.**
65
66 For less sensitive information, such as testing data, use a `.npmignore` or `.gitignore` file to prevent publishing to the registry. For more information, see [this article][developers].
67
68 ## Testing your package
69
70 To reduce the chances of publishing bugs, we recommend testing your package before publishing it to the npm registry. To test your package, run `npm install` with the full path to your package directory:
71
72 ```
73 npm install /path/to/my-test-package
74 ```
75
76 ## Publishing scoped public packages
77
78 By default, scoped packages are published with private visibility. To publish a scoped package with public visibility, use `npm publish --access public`.
79
80 There are two ways to publish your package to the npm registry:
81
82 1. [Direct publishing](#direct-publishing)
83 2. [Staged publishing](#staged-publishing)
84
85 ### Direct publishing
86
87 To publish directly with `npm publish --access public`, you need either:
88
89 - Two-factor authentication (2FA) enabled on your account, or
90 - A granular access token (GAT) with bypass 2FA enabled
91
92 For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
93
94 1. On the command line, navigate to the root directory of your package.
95
96 ```
97 cd /path/to/my-test-package
98 ```
99
100 2. To publish your scoped public package to the npm registry, run:
101
102 ```
103 npm publish --access public
104 ```
105
106 <Note>
107
108 **Note:** If you use GitHub Actions to publish your packages, you can generate provenance information for each package you publish. For more information, see "[Generating provenance statements][provenance-how-to]."
109
110 </Note>
111
112 3. To see your public package page, visit https://npmjs.com/package/\*package-name\*, replacing \*package-name\* with the name of your package. Public packages will say `public` below the package name on the npm website.
113
114 <>{shared['organization-package-public'].image}</>
115
116 For more information on the `publish` command, see the [CLI documentation][cli-publish].
117
118 ### Staged publishing
119
120 Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package becomes publicly available, a maintainer must review and approve it with 2FA.
121
122 A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
123
124 1. On the command line, navigate to the root directory of your package.
125
126 ```
127 cd /path/to/my-test-package
128 ```
129
130 2. To stage your scoped public package, run:
131
132 ```
133 npm stage publish
134 ```
135
136 This submits your package to a staging area.
137
138 3. To check that your package has been staged, use either of the following methods:
139 - In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
140 - On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
141
142 4. To approve and publish the staged package, use one of the following methods:
143 - In the CLI, run the `npm stage approve <stage-id>` command.
144 - On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
145
146 <Note>
147
148 **Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
149
150 </Note>
151
152 For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
153
154 [scopes]: /about-scopes
155 [user-signup]: https://www.npmjs.com/signup
156 [create-org]: https://www.npmjs.com/signup?next=/org/create
157 [reg-config]: configuring-your-registry-settings-as-an-npm-enterprise-user
158 [pkg-name]: package-name-guidelines
159 [readme-file]: about-package-readme-files
160 [developers]: /misc/developers#keeping-files-out-of-your-package
161 [cli-publish]: /cli/publish
162 [pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information
163 [provenance-how-to]: /generating-provenance-statements
164 [config-2fa]: /configuring-two-factor-authentication
165 [creating-token]: /creating-and-viewing-access-tokens
166 [requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
167 [staged-publishing]: /staged-publishing