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

# Custom package registries

> Connect Superblocks to your organization's private npm registry for package installs

export const Alert = ({type, title, children}) => {
  const getIcon = () => {
    switch (type) {
      case 'info':
        return "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 20 20' fill='none'%3E%3Cpath d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm0 15c-.552 0-1-.448-1-1s.448-1 1-1 1 .448 1 1-.448 1-1 1zm1-3H9V6h2v6z' fill='%230099FF'/%3E%3C/svg%3E";
      case 'success':
        return "data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 0 20 20' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill-rule='evenodd' clip-rule='evenodd' d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm4.293 6.293L9 11.586 5.707 8.293c-.391-.391-1.024-.391-1.414 0s-.391 1.024 0 1.414l4 4c.391.391 1.024.391 1.414 0l6-6c.391-.391.391-1.024 0-1.414s-1.024-.391-1.414 0z' fill='%230CC26D'/%3E%3C/svg%3E";
      case 'warning':
        return "data:image/svg+xml;charset=utf-8;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHhtbDpzcGFjZT0ncHJlc2VydmUnIHdpZHRoPScxMDgwJyBoZWlnaHQ9JzEwODAnPjxyZWN0IHdpZHRoPScxMDAlJyBoZWlnaHQ9JzEwMCUnIGZpbGw9J3RyYW5zcGFyZW50Jy8+PHBhdGggZD0nTTEzLjc5NCAxMC43NSA4LjMgMS4yNWExLjUgMS41IDAgMCAwLTIuNiAwbC01LjQ5NCA5LjVBMS40OTQgMS40OTQgMCAwIDAgMS41IDEzaDExYTEuNDkzIDEuNDkzIDAgMCAwIDEuMjk0LTIuMjVNNi41IDUuNWEuNS41IDAgMCAxIDEgMFY4YS41LjUgMCAwIDEtMSAwek03IDExYS43NS43NSAwIDEgMSAwLTEuNS43NS43NSAwIDAgMSAwIDEuNScgc3R5bGU9J3N0cm9rZTpub25lO3N0cm9rZS13aWR0aDoxO3N0cm9rZS1kYXNoYXJyYXk6bm9uZTtzdHJva2UtbGluZWNhcDpidXR0O3N0cm9rZS1kYXNob2Zmc2V0OjA7c3Ryb2tlLWxpbmVqb2luOm1pdGVyO3N0cm9rZS1taXRlcmxpbWl0OjQ7ZmlsbDojZmY5ZjM1O2ZpbGwtcnVsZTpub256ZXJvO29wYWNpdHk6MScgdHJhbnNmb3JtPSd0cmFuc2xhdGUoLjAyIDE5LjMwNSlzY2FsZSg3Ny4xNCknLz48L3N2Zz4=";
      case 'danger':
        return "data:image/svg+xml,%3Csvg width='20' height='20' viewBox='0 0 20 20' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm5.707 4.293L10 9.586 4.293 4.293c-.391-.391-1.024-.391-1.414 0s-.391 1.024 0 1.414L8.586 11l-5.707 5.293c-.391.391-.391 1.024 0 1.414s1.024.391 1.414 0L10 12.414l5.707 5.293c.391.391 1.024.391 1.414 0s.391-1.024 0-1.414L11.414 11l5.707-5.293c.391-.391.391-1.024 0-1.414s-1.024-.391-1.414 0z' fill='%23F45252'/%3E%3C/svg%3E";
      case 'note':
        return "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='20' height='20' viewBox='0 0 20 20' fill='none'%3E%3Cpath d='M10 0C4.477 0 0 4.477 0 10s4.477 10 10 10 10-4.477 10-10S15.523 0 10 0zm0 15c-.552 0-1-.448-1-1s.448-1 1-1 1 .448 1 1-.448 1-1 1zm1-3H9V6h2v6z' fill='%230099FF'/%3E%3C/svg%3E";
      default:
        return "";
    }
  };
  return <div className={`alert alert--${type}`}>
      <div className="alert-icon" style={{
    backgroundImage: `url("${getIcon()}")`,
    backgroundRepeat: 'no-repeat',
    backgroundPosition: 'center center',
    backgroundSize: '20px',
    width: '24px',
    height: '24px',
    position: 'absolute',
    left: '16px',
    top: '16px'
  }} />
      <div className="alert-content">
        {title && <div className="alert-title">{title}</div>}
        <div className="alert-body">{children}</div>
      </div>
    </div>;
};

<Note>
  Package registry configuration is currently in **beta**. [Contact support](mailto:support@superblocks.com) to enable it for your organization.
</Note>

<Alert type="note">
  <p>
    <strong>Who can use this feature?</strong><br />
    Organization admins with the appropriate permissions can configure package registry settings.
  </p>
</Alert>

Admins can configure Superblocks to resolve npm packages from a private registry instead of the public npm registry. When configured, every package install triggered by [Clark AI](/building-with-clark/index) flows through your registry.

This is useful when your organization:

* **Restricts public internet egress** and routes all package fetches through an internal registry (e.g. Artifactory, Nexus, Verdaccio)
* **Requires supply-chain review** before packages can be installed (e.g. an allowlist-gated registry)
* **Serves internal packages** such as a private design system or shared component library

Once configured, every `npm install` in both Edit mode and production builds uses your registry. Clark checks package availability against your registry before attempting installs, and provides clear feedback when a package is unavailable.

## Configure a private registry

1. Navigate to **Organization Settings > Package Registry**
2. Enter your **Registry URL**, the full URL of your npm-compatible registry (e.g. `https://artifactory.example.com/api/npm/npm-virtual/`)
3. Enter your **Auth token**, a token with read access to your registry. The token is encrypted at rest and never exposed in the UI after saving
4. Click **Save**

| Field            | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| **Registry URL** | The full URL of your npm-compatible registry. Must use HTTPS                      |
| **Auth token**   | An authentication token for the registry. Stored encrypted; redacted after saving |

<Warning>
  The registry URL must use `https://`. HTTP URLs are rejected to prevent credentials from being sent in cleartext.
</Warning>

<Warning>
  Before creating your first app, ensure your registry serves the [core required packages](#core-required-packages) and their transitive dependencies. The editor will not start if any are missing.
</Warning>

## Allow install scripts

Separately from registry configuration, admins can control whether npm packages are allowed to run post-install scripts. This is an organization-wide setting that applies to all package installs regardless of which registry is configured.

Some npm packages run post-install scripts during installation. For example, `sharp` and `better-sqlite3` compile native binaries. Disabling install scripts reduces your supply-chain attack surface by preventing arbitrary code execution at install time, but packages that rely on lifecycle scripts may fail to build.

Toggle **Allow packages to run post-install scripts** on the Package Registry page based on your organization's security posture:

| Setting               | Behavior                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------ |
| **Enabled** (default) | Packages can run post-install scripts normally                                             |
| **Disabled**          | All `npm install` commands include `--ignore-scripts`, blocking lifecycle script execution |

## How Clark interacts with your registry

When a builder asks Clark to install a package, Clark checks your configured registry before attempting the install:

1. Clark queries your registry to confirm the package is available
2. If the package is found, Clark proceeds with the install
3. If the package is **not found** in your registry, Clark explains the situation and suggests the builder contact their admin to add the package to the registry's approved list

This ensures Clark is aware of your registry configuration and can give builders clear feedback when a package install fails.

### Error messages

When a package install fails, Clark provides a structured explanation based on the failure type:

| Error                              | Meaning                                                                                                                       |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Package not in registry**        | The requested package is not available in your organization's registry. Ask your admin to add it to the approved package list |
| **Registry authentication failed** | The configured auth token is invalid or expired. An admin needs to update the token in Package Registry settings              |
| **Registry unreachable**           | The registry could not be reached. Check network connectivity and registry availability                                       |

## Enforcement model

Superblocks configures `npm` to use your registry for all Clark-triggered installs. Clark also checks package availability against your registry before attempting installs.

For [cloud-prem](/enterprise/cloud-prem/aws) customers who own their network infrastructure, you can combine the Package Registry configuration with network-level controls (e.g. VPC egress rules, NetworkPolicy) that block traffic to `registry.npmjs.org` for full enforcement in egress-restricted environments.

## Core required packages

Every Superblocks application ships with a fixed set of npm dependencies. All of these must be resolvable from your registry, or the editor will not start.

There are two tiers:

* **Platform-critical**: the editor, dev server, and build pipeline require these to function. Clark will never suggest removing them; the only fix for a missing one is for an admin to mirror it into the registry.
* **Template defaults**: included in new apps (e.g. Radix UI, Lucide, Recharts). Clark can refactor these away if a builder asks, but they must be available when an app is first created.

### Platform-critical packages

These packages cannot be removed or replaced. If any are missing from your registry, the editor will fail to start and Clark cannot work around it.

#### `@superblocksteam/*` scoped packages

All packages under the `@superblocksteam` scope are platform-owned and protected. These are published to the public npm registry (`registry.npmjs.org`).

| Package                            | Role                                                     |
| ---------------------------------- | -------------------------------------------------------- |
| `@superblocksteam/library`         | Core runtime library (component model, state, evaluator) |
| `@superblocksteam/sdk-api`         | SDK API type definitions                                 |
| `@superblocksteam/library-shared`  | Shared types consumed by the library and platform        |
| `@superblocksteam/shared`          | Platform-wide shared types and protobuf definitions      |
| `@superblocksteam/types`           | Generated protobuf type bindings                         |
| `@superblocksteam/sabs-types`      | Build service type definitions                           |
| `@superblocksteam/fast-deep-equal` | Deep-equality utility                                    |
| `@superblocksteam/cli`             | Official Superblocks CLI (local dev, resource sync)      |
| `@superblocksteam/iso-currency`    | Currency formatting and data                             |

#### Unscoped platform packages

| Package             | Role                                 |
| ------------------- | ------------------------------------ |
| `react`             | React runtime                        |
| `react-dom`         | React DOM renderer                   |
| `react-router`      | App page routing                     |
| `react-router-dom`  | Legacy routing (brownfield apps)     |
| `vite`              | Dev server and production build tool |
| `typescript`        | Type checking in the build pipeline  |
| `@tailwindcss/vite` | Tailwind CSS Vite plugin             |
| `tailwindcss`       | Tailwind CSS framework               |

### Full dependency closure

A newly created app installs approximately 780 npm packages (direct + transitive). The exact set depends on your Superblocks version.

<Tabs>
  <Tab title="Pull-through cache (Artifactory, Nexus, Verdaccio proxy)">
    If your registry is configured as a remote proxy, it will automatically fetch transitive dependencies on cache miss. Ensure the platform-critical packages listed above are reachable through your proxy, and the rest will resolve automatically.

    The first app creation may be slower than usual while the cache warms.
  </Tab>

  <Tab title="Curated allowlist">
    If your registry requires explicit approval for every package, you need the full dependency closure. Download the complete package list and feed it to your approval pipeline:

    <a href="/admin/assets/superblocks-core-packages.json" download>Download superblocks-core-packages.json</a>

    This JSON file lists all \~780 packages with their versions. Use it to verify your registry covers every required dependency.

    <Note>
      Approximately 63 of these packages are **platform-specific optional binaries** (`@esbuild/linux-x64`, `@rollup/rollup-darwin-arm64`, etc.). npm only installs the ones matching the target platform, but your registry must serve the binaries for every platform where Superblocks runs.
    </Note>
  </Tab>
</Tabs>

<Info>
  Package versions and transitive dependencies may change between Superblocks releases. Use the [Superblocks MCP server](/admin/mcp-server) to query packages currently in use across your organization for the latest inventory.
</Info>

## Package inventory

Admins can view the distinct set of npm packages in use across all applications in the organization using the [Superblocks MCP server](/admin/mcp-server). Compare the output against the [core required packages](#core-required-packages) to verify your registry covers the baseline. This is useful for:

* **Registry reconciliation**: compare installed packages against what your private registry serves to find gaps before they cause install failures
* **Audit and compliance**: maintain visibility into your organization's npm dependency footprint
* **Migration planning**: identify which apps need attention when tightening registry policies

Ask your AI coding agent:

```text theme={null}
What npm packages are in use across my Superblocks organization?
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Installs fail with 'package not in registry'">
    The requested package exists on public npm but has not been added to your private registry. If your registry is a **pull-through cache** (e.g. Artifactory configured as a remote proxy), the package should appear automatically on first request. If your registry uses a **curated allowlist**, your security team needs to approve and mirror the package before it can be installed.
  </Accordion>

  <Accordion title="Installs fail with 'registry authentication failed'">
    The auth token saved in Package Registry settings is invalid or expired. Navigate to **Organization Settings > Package Registry**, enter a fresh token, and save. Tokens from registries like Artifactory and Nexus may have expiration policies. Coordinate with your registry administrator on rotation schedules.
  </Accordion>

  <Accordion title="Installs fail with 'registry unreachable'">
    Superblocks could not reach your registry. Common causes:

    * The registry URL is incorrect or has a typo
    * The registry is behind a firewall that does not allow traffic from Superblocks infrastructure
    * The registry service is temporarily down

    Verify the URL is correct and that your registry is accessible from the network where Superblocks runs. For [cloud-prem](/enterprise/cloud-prem/aws) deployments, ensure the Superblocks data plane has network connectivity to your registry.
  </Accordion>

  <Accordion title="Editor fails to start after configuring a private registry">
    The editor requires approximately 780 npm packages (direct + transitive) to boot a new 3.0 app. If any are missing from your registry, the dev server will fail to start. Check the [core required packages](#core-required-packages) section and ensure all platform-critical packages and their transitive dependencies are available. For pull-through caches, the first app creation may be slower than usual while packages are fetched on cache miss.
  </Accordion>

  <Accordion title="Native packages fail to build after disabling install scripts">
    Packages like `sharp`, `better-sqlite3`, and `node-canvas` require post-install scripts to compile native binaries. If you disabled **Allow packages to run post-install scripts**, these packages will fail to build.

    Either re-enable install scripts, or work with your security team to pre-build and publish these native packages as pre-compiled binaries in your registry.
  </Accordion>
</AccordionGroup>