249 lines
9.3 KiB
Markdown
249 lines
9.3 KiB
Markdown
|
---
|
||
|
stage: Package
|
||
|
group: Package Registry
|
||
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
||
|
---
|
||
|
|
||
|
# Publish packages with Yarn
|
||
|
|
||
|
Publish npm packages in your project's Package Registry using Yarn. Then install the
|
||
|
packages whenever you need to use them as a dependency.
|
||
|
|
||
|
Learn how to build a [yarn](../workflows/build_packages.md#yarn) package.
|
||
|
|
||
|
You can get started with Yarn 2 by following the [Yarn documentation](https://yarnpkg.com/getting-started/install/).
|
||
|
|
||
|
## Publish to GitLab Package Registry
|
||
|
|
||
|
### Authentication to the Package Registry
|
||
|
|
||
|
You need a token to publish a package. Different tokens are available depending on what you're trying to
|
||
|
achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry).
|
||
|
|
||
|
- If your organization uses two-factor authentication (2FA), you must use a personal access token with the scope set to `api`.
|
||
|
- If you publish a package via CI/CD pipelines, you must use a CI job token.
|
||
|
|
||
|
Create a token and save it to use later in the process.
|
||
|
|
||
|
### Naming convention
|
||
|
|
||
|
Depending on how you install the package, you may need to adhere to the naming convention.
|
||
|
|
||
|
You can use one of two API endpoints to install packages:
|
||
|
|
||
|
- **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace.
|
||
|
- **Project-level**: Use when you have a few npm packages, and they are not in the same GitLab group.
|
||
|
|
||
|
If you plan to install a package through the [project level](#install-from-the-project-level), you do not have to
|
||
|
adhere to the naming convention.
|
||
|
|
||
|
If you plan to install a package through the [instance level](#install-from-the-instance-level), then you must name
|
||
|
your package with a [scope](https://docs.npmjs.com/misc/scope/). Scoped packages begin with a `@` and have the
|
||
|
`@owner/package-name` format. You can set up the scope for your package in the `.yarnrc.yml` file and by using the
|
||
|
`publishConfig` option in the `package.json`.
|
||
|
|
||
|
- The value used for the `@scope` is the root of the project that hosts the packages and not the root
|
||
|
of the project with the package's source code. The scope should be lowercase.
|
||
|
- The package name can be anything you want
|
||
|
|
||
|
| Project URL | Package Registry in | Scope | Full package name |
|
||
|
| ------------------------------------------------------- | ------------------- | --------- | ---------------------- |
|
||
|
| `https://gitlab.com/my-org/engineering-group/analytics` | Analytics | `@my-org` | `@my-org/package-name` |
|
||
|
|
||
|
### Configuring `.yarnrc.yml` to publish from the project level
|
||
|
|
||
|
To publish with the project-level npm endpoint, set the following configuration in
|
||
|
`.yarnrc.yml`:
|
||
|
|
||
|
```yaml
|
||
|
npmScopes:
|
||
|
foo:
|
||
|
npmRegistryServer: 'https://<your_domain>/api/v4/projects/<your_project_id>/packages/npm/'
|
||
|
npmPublishRegistry: 'https://<your_domain>/api/v4/projects/<your_project_id>/packages/npm/'
|
||
|
|
||
|
npmRegistries:
|
||
|
//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:
|
||
|
npmAlwaysAuth: true
|
||
|
npmAuthToken: '<your_token>'
|
||
|
```
|
||
|
|
||
|
In this configuration:
|
||
|
|
||
|
- Replace `<your_domain>` with your domain name.
|
||
|
- Replace `<your_project_id>` with your project's ID, which you can find on the project's home page.
|
||
|
- Replace `<your_token>` with a deploy token, group access token, project access token, or personal access token.
|
||
|
|
||
|
### Configuring `.yarnrc.yml` to publish from the instance level
|
||
|
|
||
|
For the instance-level npm endpoint, use this Yarn 2 configuration in `.yarnrc.yml`:
|
||
|
|
||
|
```yaml
|
||
|
npmScopes:
|
||
|
<scope>:
|
||
|
npmRegistryServer: 'https://<your_domain>/api/v4/packages/npm/'
|
||
|
|
||
|
npmRegistries:
|
||
|
//gitlab.example.com/api/v4/packages/npm/:
|
||
|
npmAlwaysAuth: true
|
||
|
npmAuthToken: '<your_token>'
|
||
|
```
|
||
|
|
||
|
In this configuration:
|
||
|
|
||
|
- Replace `<your_domain>` with your domain name.
|
||
|
- Your scope is `<scope>`, without `@`.
|
||
|
- Replace `<your_token>` with a deploy token, group access token, project access token, or personal access token.
|
||
|
|
||
|
### Publishing a package via the command line
|
||
|
|
||
|
Publish a package:
|
||
|
|
||
|
```shell
|
||
|
npm publish
|
||
|
```
|
||
|
|
||
|
Your package should now publish to the Package Registry.
|
||
|
|
||
|
### Publishing via a CI/CD pipeline
|
||
|
|
||
|
In the GitLab project that houses your `yarnrc.yml`, edit or create a `.gitlab-ci.yml` file. For example:
|
||
|
|
||
|
```yaml
|
||
|
image: node:latest
|
||
|
|
||
|
stages:
|
||
|
- deploy
|
||
|
|
||
|
deploy:
|
||
|
stage: deploy
|
||
|
script:
|
||
|
- npm publish
|
||
|
```
|
||
|
|
||
|
Your package should now publish to the Package Registry when the pipeline runs.
|
||
|
|
||
|
## Install a package
|
||
|
|
||
|
If multiple packages have the same name and version, the most recently-published package is retrieved when you install a package.
|
||
|
|
||
|
You can install a package from a GitLab project or instance:
|
||
|
|
||
|
- **Instance-level**: Use when you have many npm packages in different GitLab groups or in their own namespace.
|
||
|
- **Project-level**: Use when you have a few npm packages, and they are not in the same GitLab group.
|
||
|
|
||
|
### Install from the instance level
|
||
|
|
||
|
WARNING:
|
||
|
You must use packages published with the scoped [naming convention](#naming-convention) when you install a package from the instance level.
|
||
|
|
||
|
1. Authenticate to the Package Registry
|
||
|
|
||
|
If you install a package from a private project, you must authenticate to the Package Registry. Skip this step if the project is not private.
|
||
|
|
||
|
```shell
|
||
|
npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token
|
||
|
```
|
||
|
|
||
|
- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
|
||
|
- Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
|
||
|
|
||
|
1. Set the registry
|
||
|
|
||
|
```shell
|
||
|
npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
|
||
|
```
|
||
|
|
||
|
- Replace `@scope` with the [root level group](#naming-convention) of the project you're installing to the package from.
|
||
|
- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
|
||
|
- Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
|
||
|
|
||
|
1. Install the package
|
||
|
|
||
|
```shell
|
||
|
yarn add @scope/my-package
|
||
|
```
|
||
|
|
||
|
### Install from the project level
|
||
|
|
||
|
1. Authenticate to the Package Registry
|
||
|
|
||
|
If you install a package from a private project, you must authenticate to the Package Registry. Skip this step if the project is not private.
|
||
|
|
||
|
```shell
|
||
|
npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token
|
||
|
```
|
||
|
|
||
|
- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
|
||
|
- Replace `your_project_id` is your project ID, found on the project's home page.
|
||
|
- Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
|
||
|
|
||
|
1. Set the registry
|
||
|
|
||
|
```shell
|
||
|
npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
|
||
|
```
|
||
|
|
||
|
- Replace `@scope` with the [root level group](#naming-convention) of the project you're installing to the package from.
|
||
|
- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
|
||
|
- Replace `your_project_id` is your project ID, found on the project's home page.
|
||
|
|
||
|
1. Install the package
|
||
|
|
||
|
```shell
|
||
|
yarn add @scope/my-package
|
||
|
```
|
||
|
|
||
|
## Helpful hints
|
||
|
|
||
|
For full helpful hints information, refer to the [npm documentation](../npm_registry/index.md#helpful-hints).
|
||
|
|
||
|
### Supported CLI commands
|
||
|
|
||
|
The GitLab npm repository supports the following commands for the npm CLI (`npm`) and yarn CLI
|
||
|
(`yarn`):
|
||
|
|
||
|
- `npm install`: Install npm packages.
|
||
|
- `npm publish`: Publish an npm package to the registry.
|
||
|
- `npm dist-tag add`: Add a dist-tag to an npm package.
|
||
|
- `npm dist-tag ls`: List dist-tags for a package.
|
||
|
- `npm dist-tag rm`: Delete a dist-tag.
|
||
|
- `npm ci`: Install npm packages directly from your `package-lock.json` file.
|
||
|
- `npm view`: Show package metadata.
|
||
|
- `yarn add`: Install an npm package.
|
||
|
- `yarn update`: Update your dependencies.
|
||
|
|
||
|
## Troubleshooting
|
||
|
|
||
|
For full troubleshooting information, refer to the [npm documentation](../npm_registry/index.md#troubleshooting).
|
||
|
|
||
|
### Error running Yarn with the Package Registry for the npm registry
|
||
|
|
||
|
If you are using [Yarn](https://classic.yarnpkg.com/en/) with the npm registry, you may get
|
||
|
an error message like:
|
||
|
|
||
|
```shell
|
||
|
yarn install v1.15.2
|
||
|
warning package.json: No license field
|
||
|
info No lockfile found.
|
||
|
warning XXX: No license field
|
||
|
[1/4] 🔍 Resolving packages...
|
||
|
[2/4] 🚚 Fetching packages...
|
||
|
error An unexpected error occurred: "https://gitlab.example.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"".
|
||
|
info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log".
|
||
|
info Visit https://classic.yarnpkg.com/en/docs/cli/install for documentation about this command
|
||
|
```
|
||
|
|
||
|
In this case, try adding this to your `.npmrc` file (and replace `<your_token>`
|
||
|
with your personal access token or deploy token):
|
||
|
|
||
|
```plaintext
|
||
|
//gitlab.example.com/api/v4/projects/:_authToken=<your_token>
|
||
|
```
|
||
|
|
||
|
You can also use `yarn config` instead of `npm config` when setting your auth-token dynamically:
|
||
|
|
||
|
```shell
|
||
|
yarn config set '//gitlab.example.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>"
|
||
|
yarn config set '//gitlab.example.com/api/v4/packages/npm/:_authToken' "<your_token>"
|
||
|
```
|