dependabot/npm_and_yarn/main/npmcli/eslint-config-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
| 1 | --- |
| 2 | title: Creating and publishing unscoped public packages |
| 3 | --- |
| 4 | |
| 5 | As an npm user, you can create unscoped packages to use in your own projects and publish them to the npm public registry for others to use in theirs. Unscoped packages are always public and are referred to by the package name only: |
| 6 | |
| 7 | ``` |
| 8 | package-name |
| 9 | ``` |
| 10 | |
| 11 | For more information on package scope, access, and visibility, see "[Package scope, access level, and visibility][pkg-viz]". |
| 12 | |
| 13 | <Note> |
| 14 | |
| 15 | **Note:** Before you can publish public unscoped npm packages, you must [sign up](https://www.npmjs.com/signup) for an npm user account. |
| 16 | |
| 17 | </Note> |
| 18 | |
| 19 | ## Creating an unscoped public package |
| 20 | |
| 21 | 1. On the command line, create a directory for your package: |
| 22 | |
| 23 | ``` |
| 24 | mkdir my-test-package |
| 25 | ``` |
| 26 | |
| 27 | 2. Navigate to the root directory of your package: |
| 28 | |
| 29 | ``` |
| 30 | cd my-test-package |
| 31 | ``` |
| 32 | |
| 33 | 3. 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: |
| 34 | |
| 35 | ``` |
| 36 | git init |
| 37 | git remote add origin git://git-remote-url |
| 38 | ``` |
| 39 | |
| 40 | 4. In the package root directory, run the `npm init` command. |
| 41 | 5. 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]". |
| 42 | 6. Create a [README file][readme-file] that explains what your package code is and how to use it. |
| 43 | 7. In your preferred text editor, write the code for your package. |
| 44 | |
| 45 | ## Reviewing package contents for sensitive or unnecessary information |
| 46 | |
| 47 | 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.** |
| 48 | |
| 49 | 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]. |
| 50 | |
| 51 | ## Testing your package |
| 52 | |
| 53 | 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: |
| 54 | |
| 55 | ``` |
| 56 | npm install path/to/my-package |
| 57 | ``` |
| 58 | |
| 59 | ## Publishing unscoped public packages |
| 60 | |
| 61 | There are two ways to publish your package to the npm registry: |
| 62 | |
| 63 | 1. [Direct publishing](#direct-publishing) |
| 64 | 2. [Staged publishing](#staged-publishing) |
| 65 | |
| 66 | ### Direct publishing |
| 67 | |
| 68 | To publish directly with `npm publish`, you need either: |
| 69 | |
| 70 | - Two-factor authentication (2FA) enabled on your account, or |
| 71 | - A granular access token (GAT) with bypass 2FA enabled |
| 72 | |
| 73 | For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification). |
| 74 | |
| 75 | 1. On the command line, navigate to the root directory of your package. |
| 76 | |
| 77 | ``` |
| 78 | cd /path/to/package |
| 79 | ``` |
| 80 | |
| 81 | 2. To publish your public package to the npm registry, run: |
| 82 | |
| 83 | ``` |
| 84 | npm publish |
| 85 | ``` |
| 86 | |
| 87 | <Note> |
| 88 | |
| 89 | **Note:** If you use GitHub Actions, GitLab CI/CD, or CircleCI to publish your packages, consider using [trusted publishing](/trusted-publishers) for enhanced security. Trusted publishing eliminates the need for access tokens in your CI/CD workflows. For GitHub Actions and GitLab CI/CD, it also automatically generates provenance information. For more information, see "[Generating provenance statements][provenance-how-to]." |
| 90 | |
| 91 | </Note> |
| 92 | |
| 93 | 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. |
| 94 | |
| 95 | For more information on the `publish` command, see the [CLI documentation][cli-publish]. |
| 96 | |
| 97 | ### Staged publishing |
| 98 | |
| 99 | 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. |
| 100 | |
| 101 | A GAT with bypass 2FA does not bypass the 2FA check during staged package approval. |
| 102 | |
| 103 | 1. On the command line, navigate to the root directory of your package. |
| 104 | |
| 105 | ``` |
| 106 | cd /path/to/package |
| 107 | ``` |
| 108 | |
| 109 | 2. To stage your package, run: |
| 110 | |
| 111 | ``` |
| 112 | npm stage publish |
| 113 | ``` |
| 114 | |
| 115 | This submits your package to a staging area. |
| 116 | |
| 117 | 3. To check that your package has been staged, use either of the following methods: |
| 118 | - In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID. |
| 119 | - On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages. |
| 120 | |
| 121 | 4. To approve and publish the staged package, use one of the following methods: |
| 122 | - In the CLI, run the `npm stage approve <stage-id>` command. |
| 123 | - On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**. |
| 124 | |
| 125 | <Note> |
| 126 | |
| 127 | **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. |
| 128 | |
| 129 | </Note> |
| 130 | |
| 131 | For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing]. |
| 132 | |
| 133 | [pkg-viz]: package-scope-access-level-and-visibility |
| 134 | [user-signup]: https://www.npmjs.com/signup |
| 135 | [create-org]: https://www.npmjs.com/signup?next=/org/create |
| 136 | [pkg-name]: package-name-guidelines |
| 137 | [readme-file]: about-package-readme-files |
| 138 | [developers]: /misc/developers#keeping-files-out-of-your-package |
| 139 | [cli-publish]: /cli/publish |
| 140 | [pii]: https://en.wikipedia.org/wiki/Personally_identifiable_information |
| 141 | [provenance-how-to]: /generating-provenance-statements |
| 142 | [config-2fa]: /configuring-two-factor-authentication |
| 143 | [creating-token]: /creating-and-viewing-access-tokens |
| 144 | [requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification |
| 145 | [staged-publishing]: /staged-publishing |