Setup Unity Package Registry

2025-05-27 09:11 UTC gpt-4o Open in ChatGPT ↗

Setting up a package registry in Unity involves hosting your own custom package registry or connecting Unity to one (like a private or self-hosted NPM registry). This is useful for sharing internal tools, SDKs, or game systems across projects or teams.

📦 Step-by-Step Guide to Set Up a Custom Package Registry in Unity

✅ 1. Understand Unity’s Package System

Unity uses the UPM (Unity Package Manager), which is based on NPM. Unity supports packages from:

Unity Registry (official)
Git repositories
Local paths
Custom scoped registries (e.g. a private NPM registry)

✅ 2. Set Up Your Own Package Registry (Optional)

You can use tools like:

Verdaccio – lightweight, easy to set up
Sonatype Nexus, Artifactory, or other enterprise solutions

🛠 Example: Set up Verdaccio (Quickest Way)

a. Install Node.js & Verdaccio

npm install -g verdaccio

b. Start Verdaccio

verdaccio

It runs at http://localhost:4873 by default.

c. Publish Your Unity Package

Create a Unity package directory (with a package.json)
Run:

npm login --registry http://localhost:4873
npm publish --registry http://localhost:4873

Make sure your package.json has a scope (e.g. @mycompany/mypackage)

✅ 3. Add the Registry to Unity

Edit your Unity project’s Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "MyCompany",
      "url": "http://localhost:4873",
      "scopes": [ "mycompany" ]
    }
  ],
  "dependencies": {
    "mycompany.mypackage": "1.0.0"
  }
}

📌 scopes must match the prefix in your package name: @mycompany/mypackage

✅ 4. Create a Unity-Compatible Package

Ensure your package folder contains:

package.json – with name, version, displayName, description
Runtime/ and/or Editor/ folders
Optional: Documentation~, Tests, Samples~

Example package.json:

{
  "name": "mycompany.mypackage",
  "version": "1.0.0",
  "displayName": "My Package",
  "description": "A useful internal Unity package.",
  "unity": "2020.3",
  "author": {
    "name": "MyCompany"
  }
}

✅ 5. Test Your Setup

Restart Unity
Check if the package appears under “In Project” in the Package Manager
Confirm the content is imported and usable

🧠 Pro Tips

You can serve your registry remotely (e.g. on a shared dev server or intranet)
Use HTTPS for real-world projects and team use
Version control your packages independently from your main project

Let me know if you want a Docker-based setup or a cloud deployment guide for Verdaccio!

Great question.

🎯 Most Common Approach to Package Management in Unity

For most indie devs, teams, and even Unity veterans, the most common and practical approach is:

✅ Using Git-based Unity packages, optionally combined with a scoped NPM/UPM registry for internal distribution.

🧰 Why Git is the Most Common Approach

✅ Advantages:

No need to set up a registry
Native Unity support
Version control integrated
Supports private Git hosting (GitHub, GitLab, Azure, etc.)

Simple to reference:

"dependencies": {
  "com.mycompany.mypackage": "https://github.com/username/repo.git#1.2.3"
}

👤 What Does Keijiro Takahashi Use?

Keijiro is a well-known Unity developer who publishes many advanced tools, particularly for graphics, shaders, and VFX.

🧪 His approach:

✅ Git-based Unity packages hosted on GitHub
❌ No custom registry (at least not publicly)
✅ Uses semantic versioning and Git tags for releases
✅ Repositories are structured as Unity packages with package.json

Example from one of his repositories:
Keijiro/Klak — a Git-based package used via:

"com.keijiro.klak": "https://github.com/keijiro/Klak.git#1.0.0"

🧱 Folder Structure He Uses

His Unity packages typically follow this layout:

Assets/
Packages/
  com.keijiro.mypackage/
    package.json
    Runtime/
    Editor/
    README.md

Or in a GitHub repo directly:

├── package.json
├── Runtime/
├── Editor/
├── README.md

This allows users to add it via Git and Unity’s Package Manager will import it correctly.

🚀 TL;DR Recommendation for Most Devs (and Keijiro-style)

✅ Use GitHub-hosted Unity packages
✅ Tag versions in Git (git tag 1.0.0)
✅ Reference via Git URLs in manifest.json
✅ Use Unity’s Packages/ structure with a proper package.json

Let me know if you want a template Unity package like Keijiro’s, or a Git automation setup for publishing versioned packages!

You’re absolutely right—Keijiro does utilize a scoped registry for distributing many of his Unity packages.

📦 Keijiro’s Use of Scoped Registries

Keijiro hosts his packages on the public NPM registry (https://registry.npmjs.com) under the scope jp.keijiro. To access these packages in your Unity project, you can add a scoped registry entry in your Packages/manifest.json file:



{
  "scopedRegistries": [
    {
      "name": "Keijiro",
      "url": "https://registry.npmjs.com",
      "scopes": [ "jp.keijiro" ]
    }
  ],
  "dependencies": {
    "jp.keijiro.metamesh": "1.0.0"
  }
}



This setup allows Unity’s Package Manager to fetch packages like jp.keijiro.metamesh directly from the NPM registry. citeturn0search0

🔧 How to Add Keijiro’s Scoped Registry in Unity

Open Project Settings: In Unity, navigate to Edit > Project Settings > Package Manager.
Add Scoped Registry:
- Name: Keijiro
- URL: https://registry.npmjs.com
- Scope(s): jp.keijiro
Save and Close: Unity will now recognize packages under the jp.keijiro scope.

Alternatively, you can manually edit the Packages/manifest.json file as shown above.

🧩 Accessing Keijiro’s Packages

After setting up the scoped registry, you can install Keijiro’s packages via the Unity Package Manager:

Open Package Manager: Go to Window > Package Manager.
Select Registry: In the Package Manager window, select My Registries from the dropdown menu.
Install Package: Find the desired package (e.g., jp.keijiro.metamesh) and click Install.

If the package doesn’t appear in the list, you can manually add it by clicking the + button and selecting Add package by name..., then entering the package name and version. citeturn0search0

🧠 Summary

Keijiro distributes his Unity packages using a scoped registry hosted on NPM under the jp.keijiro scope. By configuring your Unity project to recognize this scoped registry, you can easily access and integrate his packages into your workflow.

Let me know if you need assistance with setting up the scoped registry or have questions about specific packages!

As of 2025, Unity’s Package Manager (UPM) does not support Git-based dependencies within a package’s package.json file. This means that if you create a Unity package and specify a dependency using a Git URL inside its package.json, Unity will not resolve it. citeturn0search6

✅ What Works

You can add Git-based packages directly to your project’s Packages/manifest.json file. This allows Unity to fetch and include packages from Git repositories:



{
  "dependencies": {
    "com.example.mypackage": "https://github.com/username/repo.git#v1.0.0"
  }
}



This method is supported and commonly used for integrating external packages hosted on platforms like GitHub.

❌ What Doesn’t Work

Attempting to declare Git-based dependencies inside a package’s own package.json file is not supported. For example:



{
  "name": "com.example.mytoolkit",
  "version": "1.0.0",
  "dependencies": {
    "com.example.utility": "https://github.com/username/utility.git"
  }
}



This configuration will result in errors during package resolution. citeturn0search6

🛠 Workarounds

To manage Git-based dependencies within packages, consider the following approaches:

Use a Dependency Resolver Plugin: Tools like GitDependencyResolverForUnity can process custom fields (e.g., gitDependencies) in your package.json and fetch the necessary Git-based packages. This requires users of your package to install the resolver plugin in their projects.
Document Dependencies: Clearly list any required Git-based packages in your documentation, instructing users to add them to their project’s manifest.json.
Use Scoped Registries: If possible, host your packages on a scoped registry like OpenUPM. This allows you to manage dependencies more effectively and provides a centralized location for your packages.

🔍 Summary

✅ Supported: Adding Git-based packages to Packages/manifest.json.
❌ Not Supported: Declaring Git-based dependencies inside a package’s package.json.
🛠 Workarounds: Use dependency resolver plugins, document dependencies, or utilize scoped registries.

For more detailed information, refer to Unity’s official documentation on Git dependencies.

Let me know if you need assistance with setting up any of these workarounds or have further questions!