diff options
Diffstat (limited to 'doc/user/packages/npm_registry/index.md')
-rw-r--r-- | doc/user/packages/npm_registry/index.md | 26 |
1 files changed, 17 insertions, 9 deletions
diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index b1075e19b7b..f048440e383 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -86,7 +86,9 @@ A `package.json` file is created. To use the GitLab endpoint for npm packages, choose an option: - **Project-level**: Use when you have few npm packages and they are not in - the same GitLab group. + the same GitLab group. The [package naming convention](#package-naming-convention) is not enforced at this level. + Instead, you should use a [scope](https://docs.npmjs.com/cli/v6/using-npm/scope) for your package. + When you use a scope, the registry URL is [updated](#authenticate-to-the-package-registry) only for that scope. - **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace. Be sure to comply with the [package naming convention](#package-naming-convention). @@ -151,7 +153,7 @@ npm config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_tok - `<your_token>` is your personal access token or deploy token. - Replace `gitlab.example.com` with your domain name. -You should now be able to publish and install npm packages in your project. +You should now be able to install npm packages in your project. If you encounter an error with [Yarn](https://classic.yarnpkg.com/en/), view [troubleshooting steps](#troubleshooting). @@ -204,9 +206,14 @@ Then, you can run `npm publish` either locally or by using GitLab CI/CD. ## Package naming convention -Your npm package name must be in the format of `@scope/package-name`. +When you use the [instance-level endpoint](#use-the-gitlab-endpoint-for-npm-packages), only the packages with names in the format of `@scope/package-name` are available. -- The `@scope` is the root namespace of the GitLab project. It must match exactly, including the case. +- The `@scope` is the root namespace of the GitLab project. To follow npm's convention, it should be + lowercase. However, the GitLab package registry allows for uppercase. Before GitLab 13.10, the + `@scope` had to be a case-sensitive match of the GitLab project's root namespace. This was + problematic because the npm public registry does not allow uppercase letters. GitLab 13.10 relaxes + this requirement and translates uppercase in the GitLab `@scope` to lowercase for npm. For + example, a package `@MyScope/package-name` in GitLab becomes `@myscope/package-name` for npm. - The `package-name` can be whatever you want. For example, if your project is `https://gitlab.example.com/my-org/engineering-group/team-amazing/analytics`, @@ -216,7 +223,8 @@ the root namespace is `my-org`. When you publish a package, it must have `my-org | ---------------------- | ----------------------- | --------- | | `my-org/bar` | `@my-org/bar` | Yes | | `my-org/bar/baz` | `@my-org/baz` | Yes | -| `My-org/Bar/baz` | `@My-org/Baz` | Yes | +| `My-Org/Bar/baz` | `@my-org/Baz` | Yes | +| `My-Org/Bar/baz` | `@My-Org/Baz` | Yes | | `my-org/bar/buz` | `@my-org/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | @@ -229,8 +237,7 @@ In GitLab, this regex validates all package names from all package managers: This regex allows almost all of the characters that npm allows, with a few exceptions (for example, `~` is not allowed). -The regex also allows for capital letters, while npm does not. Capital letters are needed because the scope must be -identical to the root namespace of the project. +The regex also allows for capital letters, while npm does not. WARNING: When you update the path of a user or group, or transfer a subgroup or project, @@ -302,8 +309,9 @@ the same version more than once, even if it has been deleted. ## Install a package npm packages are commonly-installed by using the `npm` or `yarn` commands -in a JavaScript project. You can install a package from the scope of a project, group, -or instance. +in a JavaScript project. You can install a package from the scope of a project or instance. + +If multiple packages have the same name and version, when you install a package, the most recently-published package is retrieved. 1. Set the URL for scoped packages by running: |