> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibely.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed registry

> Publish private npm packages to a registry hosted inside your Vibely workspace and install them in your workspace's projects.

The managed registry gives your workspace its own private npm registry, hosted inside Vibely. You can publish packages to it without making them public, and any project in your workspace can install them.

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/workspace-managed-registry.webp" alt="Managed registry" width="1200" height="675" />
</Frame>

Workspace owners and admins manage access tokens. Other members can see the registry's scope, URL, and published packages.

<Note>
  Open the managed registry from **Settings → Build & deploy → Managed registry**.
</Note>

## Why use a managed registry

Teams often keep shared code, such as a design system, utility functions, or an internal API client, in private npm packages that shouldn't be public. With a managed registry you can:

* Install internal packages in Vibely projects without running your own registry.
* Keep proprietary code private.
* Reuse versioned internal libraries consistently across projects.

## Common use cases

* **Internal component libraries**: install your organization's UI components in Vibely projects.
* **Shared utilities**: reuse validation, formatting, or data-fetching code across projects.
* **Internal SDKs**: install API clients that can't be published publicly.

## Prerequisites

* The **Enterprise** plan.
* The **owner** or **admin** role to issue tokens.

## Your scope

Your registry publishes into one npm scope, taken from your workspace's slug. A workspace with the slug `acme` publishes packages named `@acme/...`. The scope can't be chosen, which is what stops one workspace from publishing into another's namespace.

If your workspace has no valid slug, the page says the registry has no scope yet. Rename the workspace in **Settings → Workspace settings** to create one.

<Warning>
  Renaming your workspace changes your npm scope. Packages already published under the old scope stay there, and new ones go to the new scope. Rename before you publish, not after.
</Warning>

## Set up the managed registry

<Steps>
  <Step title="Open the registry settings">
    Go to **Settings → Managed registry**. The page shows your **Scope** and **Registry URL**, with buttons to copy each.
  </Step>

  <Step title="Issue an access token">
    Under **Access tokens**, choose a **Capability**, give the token a name, and select **Issue token**. Copy the token right away. It's shown once and can't be retrieved again.

    | Capability | What it can do |
    | - | - |
    | **Read** | Install packages from your scope. |
    | **Publish** | Everything Read can do, plus publish new versions. |

    <Warning>
      A publish token can ship code into every project in your workspace. Give publish tokens to CI only, and use read tokens everywhere else.
    </Warning>
  </Step>

  <Step title="Publish a package">
    In your package's own repository, add the `.npmrc` snippet from the settings page, set `NPM_TOKEN` to a publish token in your CI environment, and run `npm publish`. The package name must start with your scope.
  </Step>
</Steps>

## View published packages

Published packages appear under **Published packages** on the same settings page, with how many versions each has and when it was last updated.

## Use a private package in a project

To install from the registry, your projects need a read token.

<Steps>
  <Step title="Store a read token as a build secret">
    In **Settings → Build secrets**, add a [build secret](/features/build/build-secrets) named `NPM_TOKEN` whose value is a read token.
  </Step>

  <Step title="Point your scope at the registry">
    In the **Package registries** card on the same page, select **Add registry**. Enter your scope, paste the **Registry URL**, and choose `NPM_TOKEN` as the token. Vibely keeps the matching `.npmrc` block in every project in the workspace.
  </Step>

  <Step title="Ask for the package">
    Prompt the agent with the package name, just like a public package:

    ```text wrap theme={"system"}
    Install @acme/ui-components and use it to replace the current button component.
    ```
  </Step>
</Steps>

The `.npmrc` block references the token by name, so it's never written into your project's files:

```ini theme={"system"}
@acme:registry=https://<registry-host>/npm/
//<registry-host>/npm/:_authToken=${NPM_TOKEN}
```

## Rotate or revoke a token

Tokens can't be edited in place. To rotate one:

<Steps>
  <Step title="Issue a replacement">
    Same capability, with a name that says what it's for.
  </Step>

  <Step title="Update where it's used">
    Replace the value of the build secret, or your CI variable, that holds the old token.
  </Step>

  <Step title="Revoke the old token">
    Select **Revoke** next to it. Installs and publishes using it start failing immediately, which shows you anything you missed.
  </Step>
</Steps>

Each token shows its prefix and when it was last used, so you can tell which ones are still active.

## Limits

| Limit | Value |
| - | - |
| Active tokens | 20 per workspace |
| Package name length | 214 characters, including the scope |
| Package size | 18 MB per published version |
| Registry requests | 600 per minute per token |

## FAQ

<AccordionGroup>
  <Accordion title="Do all projects in my workspace have access?">
    Yes, once the scope is added under **Package registries** with a read token. Every project in the workspace gets the same `.npmrc` block.
  </Accordion>

  <Accordion title="Can I republish a version?">
    No. A version can be published once. Publish a new version instead.
  </Accordion>

  <Accordion title="What if my packages already live in another registry?">
    You don't need the managed registry. Add that registry's token as a [build secret](/features/build/build-secrets) and add the registry under **Package registries**.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Build secrets" icon="key" href="/features/build/build-secrets">
    Where your registry token lives.
  </Card>

  <Card title="npm packages" icon="cube" href="/features/build/npm-packages">
    How Vibely installs packages.
  </Card>

  <Card title="Workspace settings" icon="sliders" href="/features/workspace/admin-settings">
    Everything else admins control.
  </Card>

  <Card title="Vibely for Enterprise" icon="building" href="/introduction/enterprise">
    What the Enterprise plan includes.
  </Card>
</CardGroup>


## Related topics

- [Workspace admin settings](/features/workspace/admin-settings.md)
- [Build secrets](/features/build/build-secrets.md)
- [Use npm packages](/features/build/npm-packages.md)
- [Vibely for Enterprise](/introduction/enterprise.md)
- [Glossary](/glossary.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.