Skip to main content

Publishing Packages

Publishing Packages​

You can use a package only after publishing it, making it publicly accessible to other packages. ADITO manages this via a package registry hosted on its GitLab.

Prerequisites for Publishing in GitLab​

Before publishing a package in GitLab, ensure the following:

  • The GitLab user has developer permissions:

    • On the specific GitLab repository, and
    • On the GitLab group containing that repository.

  • The package registry is enabled in the GitLab repository. To enable it, go to General > Settings > Visibility, Project Features & Permissions:

    package registry settings

Configuration​

.npmrc File​

Each package ("project" or "module") includes a .npmrc file at its root. This file defines:

  • The scope used in the "name" field of the corresponding package.json. For ADITO xRM projects, this scope is always @aditosoftware.
  • The package registry URL, which serves as:
    • The destination where the module is published.
    • The source from which npm downloads dependent modules into the node_modules folder during npm install.

For all modules in the ADITO xRM project, the package registry URL is:

https://gitlab.adito.de/api/v4/packages/npm/

Example .npmrc content:

npmrc

Using Multiple Registries​

You can configure multiple registries for different scopes, for example, in customer projects:

npmrc customer

Working with Local Modules​

When working with local folder paths (see chapter appendix_title), add this line to .npmrc:

install-links=false

This setting causes all npm commands (install, update, etc.) to run with the --links=false option. It creates symlinks to local modules inside node_modules instead of copying them. When not using local modules, this line has no adverse effect.

Preparing a Package for Release​

Before releasing a package, complete these steps:

  • CHANGELOG.md: Replace the "unreleased" label with the actual release date.
  • package.json:
    • Remove any prerelease version tags.
    • Update dependencies and their versions if needed.
  • Run npm install to update dependencies.
  • Set a Git tag as described in the chapter GitLab tag.

Publishing the Package​

After configuring package.json with the correct version and .npmrc, your package ("project" or "module") is ready to publish.

warning

Do not run the following steps for testing purposes to avoid spamming GitLab with fake packages.

Automated Publishing​

Typically, packages are published using a GitLab CI/CD pipeline. Manual publishing is reserved for exceptional cases. For ADITO xRM modules, the CI/CD pipeline deploys packages to both GitLab and Nexus.

Triggering Automated Publishing​

You can trigger publishing on demand, for example:

  • By setting a Git version tag following SemVer conventions (see chapter ???).
  • By merging into the master branch.

Example GitLab CI/CD Pipeline Configuration​

deploy_on_gitlab_project:
  stage: deploy
  only:
    - tags
  image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/node:19-alpine
  variables:
    GITLAB_REGISTRY: ${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/
    GITLAB_TOKEN: ${CI_JOB_TOKEN}
  script:
    - echo "//${GITLAB_REGISTRY}:_authToken=${GITLAB_TOKEN}" > .npmrc
    - npm publish --registry=https://${GITLAB_REGISTRY}

This example publishes the package within the same GitLab project.

Conditional Publishing Rules​

Define rules to trigger publishing based on conditions such as commits to specific branches:

(...)
  rules:
    - if: '$CI_PIPELINE_SOURCE == "push" && ($CI_COMMIT_BRANCH =~ /^2024/ || $CI_COMMIT_BRANCH == "master")'
      when: on_success
    - when: manual
(...)

Additional Advice for GitLab Pipeline Configuration​

  • Visit https://gitlab.adito.de/xrm-modules/ci-pipelines to find standard pipelines used in xRM project development. These include pipelines for publishing via tags, eslint checks, service scans, and Liquibase validation.
  • To use the pipeline, configure your Git project as follows:
    • Activate CI/CD under GitLab's General Settings: cicd activate
    • Under CI/CD settings, specify the pipeline file path: 
      .gitlab-ci.yml@xrm-modules/ci-pipelines
      This folder contains the pipelines mentioned above. cicd settings
  • For further customization or additional pipelines, consult the GitLab CI/CD documentation.

Manual Publishing​

Reserve manual publishing for exceptional cases. We recommend automating publishing with a GitLab CI/CD pipeline, which publishes packages to both Nexus and GitLab (see chapter Automated).

Logging into npm​

Depending on the target registry, use one of these login methods:

  • Nexus (with ADITO Designer version 2024.0.2 or later): Use the npm login command available in the context menu of package.json under "NodeJS". Enter your Nexus credentials. Note: The password appears in plain text in the terminal. This method does not work for GitLab.

  • GitLab: In .npmrc, after the GitLab registry URL, add a line with the authentication token:

    :_authToken=<PersonalAccessToken>

    Examples:

    • ADITO xRM:

      @aditosoftware:registry=https://gitlab.adito.de/api/v4/packages/npm/
      //gitlab.adito.de/api/v4/packages/npm/:_authToken=aBcdefgz2yBS-sF_S4jm

      Note: The double slashes (//) are required and do not indicate a comment.

    • Customer project:

      @aditosoftware:registry=https://nexus.adito.cloud/repository/xrm
      @mycustomer:registry=https://gitlab.adito.de/api/v4/projects/98765/packages/npm/
      //gitlab.adito.de/api/v4/projects/98765/packages/npm/:_authToken=vAbocbqz3yAS-sG_S8jm
warning

Never commit .npmrc files containing Personal Access Tokens (PAT) in clear text. Remove the PAT or replace it with a placeholder before committing. Alternatively, add .npmrc to .gitignore.

Publishing the Package​

After logging in, run the npm publish command (available in the context menu of package.json under "NodeJS"):

npm publish

This publishes the package to the registry URL specified in .npmrc, making it available for other packages to reference as dependencies or peerDependencies by scope, name, and version.

GitLab Tagging​

Follow the SemVer convention for GitLab tags; see appendix appendix_title for details.

  • Create tags on demand. Not every published version must be integrated into the base project.
  • Limit the number of major releases published, as dependent modules must update their versions and publish a major release as well.
  • Integrate a new major version into the base project only when dependent modules are compatible.
  • Changing or restricting version ranges causes a major module change, except for:
    • Removing a dependency.
    • Extending the range, e.g., from ^1.0.0 to ^1.0.0 || ^2.0.0. In this case, dependent modules face fewer restrictions and remain downward compatible.