For more information on Unity, please see:

• Unity: The official website for Unity
• Unity Docs: The official documentation for Unity
• Unity UPM: Documentation for Unity's Package Manager
• Unity UPM Scoped Registry: Documentation to setup a Scoped Package Registry

Contextual Documentation

The examples in this document are generic. Cloudsmith provides contextual setup instructions within each repository, complete with copy n' paste snippets (with your namespace/repo pre-configured).

In the following examples:

Upload a Package

Publish via npm

As Unity packages are compatible with npm registries, you can publish your Unity packages to a Cloudsmith npm registry via the native npm tooling.

Setup

The endpoint for the native npm API is:

https://npm.cloudsmith.io/OWNER/REPOSITORY/

In order to authenticate for native publishing, you can either use npm login or create an npmrc file (in your $HOME or in the project directory)

Use npm login:

npm login --registry=https://npm.cloudsmith.io/OWNER/REPOSITORY/
Username: USERNAME
Password: API-KEY
Email: YOUR-EMAIL-ADDRESS

Or create an .npmrc file with the following:

registry=https://npm.cloudsmith.io/OWNER/REPOSITORY/
//npm.cloudsmith.io/OWNER/REPOSITORY/:_authToken=API-KEY

Publish

Once you have set up the registry, you can then publish from your project directory using npm publish:

npm publish --registry=https://npm.cloudsmith.io/OWNER/REPOSITORY/

For more details on npm publish see the official npm documentation. (external link)

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

To upload via the Cloudsmith CLI / API, you'll need to generate your package first. You can do this with:

npm pack

This will generate a tarball file (.tgz) like your-package-1.2.3.tgz that you can upload.

📘

This assumes that you've created a project.json file for your project. Please see the official npmjs [package.json reference] (https://docs.npmjs.com/files/package.json) (external link) for more information.

The command to upload a Unity package via the Cloudsmith CLI is:

cloudsmith push npm OWNER/REPOSITORY PACKAGE_NAME-PACKAGE_VERSION.tgz

Example:

cloudsmith push npm your-account/your-repo com.cloudsmith.assets--1.0.0.tgz

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.

Download / Install a Package

Public Registries

To download/install a Unity package, you need to add your Cloudsmith registry to your Unity project's manifest.json file as a scoped registry:

"scopedRegistries": [
    {
      "name": "NAME",
      "url": "https://npm.cloudsmith.io/OWNER/REPOSITORY/",
      "scopes": [
        "SCOPE"
      ]
    }
  ],

You then add the packages that you wish to download and install to the dependencies section of the project manifest.json file:

 "dependencies": {
    "PACKAGE_NAME": "PACKAGE_VERSION"
  }
}

For example:

{
  "scopedRegistries": [
    {
      "name": "MyRegistry",
      "url": "https://npm.cloudsmith.io/demo/examples-repo/",
      "scopes": [
        "com.cloudsmith",
      ]
    }
  ],
  
  "dependencies": {
    "com.cloudsmith.assets": 1.1.2"
  }
}

For further information, please see the Unity documentation on Scoped Registries.

Private Registries

To download/install a Unity package from a private Cloudsmith registry:

1. Add the registry and dependencies to your project's manifest.json as per the instructions for public registries
2. Locate the upmconfig.toml file and add the one of the following, depending on which authentication method you wish to use:

[npmAuth."https://npm.cloudsmith.io/OWNER/REPOSITORY/"]
token = "TOKEN"
email = "EMAIL"    OPTIONAL
alwaysAuth = true  OPTIONAL

[npmAuth."https://npm.cloudsmith.io/OWNER/REPOSITORY/"]
token = "API-KEY"
email = "EMAIL"    OPTIONAL
alwaysAuth = true  OPTIONAL

If the file does not already exist, create an empty text file.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs.

Unity Package Manager Global configuration file location:

Unity Package Manager User configuration file location:

For further information, please see the Unity documentation on scoped registry authentication

Key Signing Support

GPG

Troubleshooting

Please see the Troubleshooting page for further help and information.