Private registries

Point Superblocks at the npm registries your organization already trusts. Instead of resolving packages from public npm, your builders and Clark AI install from a registry you control. Configure a private registry to:

Control what gets installed by resolving dependencies from an allowlist-gated or scanned registry (e.g. Artifactory, Nexus, Verdaccio) instead of the open ecosystem
Reuse your own packages, such as a shared design system, component library, or internal utilities published under your own npm scope (e.g. @mycompany)
Fit your network model in egress-restricted environments where package traffic must flow through an internal registry

Once configured, installs resolve through your registries in both Edit mode and production builds.

How registries are matched

Superblocks lets you configure two kinds of registry, mirroring how npm resolves packages through an .npmrc file:

A default registry (unscoped): the fallback for every package that isn’t matched by a scoped registry.
Any number of scoped registries, each pinned to a single npm scope (e.g. @mycompany). Packages under that scope resolve from the scoped registry; everything else falls through to the default.

For example, if a default registry is configured, plus a @mycompany scoped registry, @mycompany/design-system will resolve from https://npm.internal.mycompany.com/, while an unscoped package like lodash (or a public-scope package) resolves from the default registry. If no default registry is configured, packages with no matching scoped registry resolve from the public npm registry (registry.npmjs.org).

Configure the default registry

The Package Registry page has three parts: the install policy at the top, the default registry row, and any scoped registries you add below it.

Package Registry settings page showing the Install policy card and an unconfigured default registry row

Navigate to Organization Settings > Package Registry
In the Default row under Package Registries, enter your Registry URL, the full URL of your npm-compatible registry (e.g. https://artifactory.example.com/api/npm/npm-virtual/)
Optionally enter an Auth token, a bearer token with read access to your registry (see Manage auth tokens). The token is encrypted at rest and never exposed in the UI after saving
Click Test connection. Save stays disabled until the probe succeeds (see Verify a registry)
Click Save

Field	Description
Registry URL	The full URL of your npm-compatible registry. Must use HTTPS
Auth token	An optional bearer token for the registry. Basic-auth credentials are not supported. Stored encrypted; redacted after saving

Add a scoped registry

Scoped registries route packages under a specific npm scope to a dedicated registry, while all other packages continue to use the default registry.

On the Package Registry page, click Add scoped registry
Enter the Scope the registry serves, e.g. @mycompany (see Scope format)
Enter the Registry URL and, optionally, an Auth token, using the same rules as the default registry
Click Test connection to verify the registry
Click Save

Saved scoped registries appear as collapsible rows under the default registry, each showing its scope, URL, and connection status. Click a row to expand and edit it.

Scope format

A scope must:

Start with @
Use only lowercase letters, digits, ., _, and -, beginning with a letter or digit after the @ (e.g. @my-company, @team.internal)
Be unique within your organization; you can configure at most one registry per scope

Scopes are normalized to lowercase, matching how npm itself treats them. Uppercase input (e.g. @MyCompany) is lowercased automatically.

Supported registries

Superblocks works with any npm-compatible registry. The tabs below show how to get the auth token and registry URL for the most common ones, assuming your registry already exists and serves the packages you need. Not every registry can be your default. A default registry has to resolve every package a Superblocks app needs, including the ~780 packages in the core dependency closure, so it must proxy or mirror public npm. Registries that only host your organization’s own packages must be added as scoped registries instead.

Verdaccio can be used as a default or scoped registry: as the default when its ** package group proxies an npm uplink, or as a scoped registry when it only hosts your internal packages.Verdaccio issues npm tokens through the npm CLI. Log in as a user with read access to the packages Superblocks will install, then mint a read-only token:

npm login --registry https://npm.example.com/
npm token create --read-only --registry https://npm.example.com/

Copy the token value from the command output. If your Verdaccio config grants access: $all, reads are anonymous and you can leave Auth token blank.Registry URL: your Verdaccio base URL, e.g. https://npm.example.com/

Artifactory can be used as a default or scoped registry: point the default at a virtual repository that includes a remote (proxy) repository, or use a local repository, which serves only packages you publish, as a scoped registry.Use an identity token belonging to a service user with read permission on the repository:

Log in to Artifactory as the service user
Go to User menu > Edit Profile > Generate an Identity Token
Copy the token, which is shown only once

A scoped access token with read permission works as well. Don’t use the user’s password, and don’t embed credentials in the URL.Registry URL: the npm API path for your virtual repository, e.g. https://mycompany.jfrog.io/artifactory/api/npm/npm-virtual/ (self-hosted: https://artifactory.example.com/artifactory/api/npm/npm-virtual/)

Nexus can be used as a default or scoped registry: point the default at a group repository that includes an npm proxy, or use a hosted repository, which serves only packages you publish, as a scoped registry.To get a token:

Enable the npm Bearer Token Realm under Administration > Security > Realms. Without it, Nexus ignores the _authToken Superblocks sends
As a service account with read access (nx-repository-view-npm-*-read), log in through npm and copy the generated token out of your .npmrc:
npm login --registry https://nexus.example.com/repository/npm-all/ grep _authToken ~/.npmrc

If anonymous read access is enabled on the repository, leave Auth token blank.Registry URL: your repository URL, e.g. https://nexus.example.com/repository/npm-all/

CodeArtifact can be used as a default or scoped registry: as the default when the repository has a public:npmjs external connection (directly or through an upstream), or as a scoped registry when it serves only packages you publish.CodeArtifact tokens come from the AWS CLI. Use an IAM user or role (not the root user) with codeartifact:GetAuthorizationToken, codeartifact:ReadFromRepository, codeartifact:GetRepositoryEndpoint, and sts:GetServiceBearerToken:

aws codeartifact get-authorization-token \
  --domain mycompany --duration-seconds 43200 \
  --query authorizationToken --output text

Get the matching registry URL with:

aws codeartifact get-repository-endpoint \
  --domain mycompany --repository superblocks --format npm

Registry URL: e.g. https://mycompany-111122223333.d.codeartifact.us-east-1.amazonaws.com/npm/superblocks/

GitHub Packages can only be used as a scoped registry. It serves only packages named @OWNER/package and never proxies public npm, so it can’t resolve the core required packages, and using it as the default registry prevents the editor from starting. Set the Scope to the GitHub account name, lowercased (e.g. @mycompany), and keep a proxying registry (or public npm) as the default.Create a personal access token (classic) with the read:packages scope, owned by a machine user that has read access to the packages. That token value is the _authToken.GITHUB_TOKEN and fine-grained tokens don’t work here: the former is scoped to a single workflow run, and the latter doesn’t cover the npm registry.Registry URL: https://npm.pkg.github.com

The GitLab package registry can only be used as a scoped registry, matching your GitLab namespace scope (e.g. @mycompany). It serves only packages scoped to its own namespaces and isn’t a public npm mirror: request forwarding to npmjs.com is an admin-toggleable Premium/Ultimate self-managed setting, not a substitute for a proxy. Keep a proxying registry as the default.Create a deploy token with the read_package_registry scope. A group-level deploy token is the most durable option, since it isn’t tied to a user. A personal access token with the api scope also works. Use the token value as the _authToken.Registry URL: whichever endpoint matches how your packages are organized:

Endpoint	URL
Instance	`https://gitlab.example.com/api/v4/packages/npm/`
Group	`https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/`
Project	`https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/`

GitLab.com uses the same paths under https://gitlab.com.

Verify a registry

Click Test connection next to any Registry URL to probe the registry before (or after) saving. Superblocks resolves the host, opens a connection, and reports a status badge on the row:

Badge	Meaning
Reachable	The registry responded and, if a token was supplied, accepted it
Reachable, token not verified	The registry responded but doesn’t expose `/-/whoami`, so the token couldn’t be validated. Install problems will only surface when Clark or a build job actually installs a package
Unreachable (or a specific error)	The probe failed. See the reason below the field

Common failure reasons:

Reason	Meaning
Couldn’t reach the registry	The host could not be resolved or connected to
The registry returned an invalid TLS certificate	TLS/certificate validation failed
The registry rejected your auth token	Authentication failed. Check the token
This registry requires authentication (supply an auth token and re-test)	The registry needs a token but none was provided
This URL doesn’t look like an npm registry	The endpoint didn’t respond like an npm registry
The registry took too long to respond	The probe timed out
A network proxy blocked the request	An outbound proxy blocked the connection

Manage auth tokens

The Auth token must be a bearer token. Superblocks always sends it as the npm _authToken, which reaches your registry as an Authorization: Bearer <token> header. That is true on every path: the Test connection probe, and every install forwarded through the Superblocks proxy. Leave the field blank for registries that serve anonymous reads. Once saved, a token is write-only:

It is encrypted at rest and never retrievable from the dashboard; the field shows only a redacted preview.
To rotate it, enter a new value and save.
To remove it, click Clear token and save.

Rotate tokens with the API

Registries that issue short-lived tokens, such as AWS CodeArtifact with its 12 hour maximum lifetime, need the stored token refreshed regularly. Rather than pasting a new value by hand, rotate it programmatically on a schedule (for example a cron job in CI, or an EventBridge-triggered Lambda) using the Superblocks npm registry API. Authenticate the calls with the personal API key of a user who has permission to update package registries, sent as a bearer token. Copy it from Personal Settings > API Key (see Access tokens). Org-level access tokens don’t work for these endpoints. For automation, use the key of a dedicated service user rather than an individual’s, so rotation keeps working when someone’s permissions or employment change. First list your registries to find the ID of the one to update:

curl --location --globoff 'https://<tenant>.superblocks.com/api/v1/organizations/<ORGANIZATION_ID>/npm-registry' \
  --header 'Authorization: Bearer <PERSONAL_API_KEY>'

Then PUT the new token, passing the registry URL along with it:

curl --location --globoff --request PUT 'https://<tenant>.superblocks.com/api/v1/organizations/<ORGANIZATION_ID>/npm-registry/<REGISTRY_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PERSONAL_API_KEY>' \
  --data '{
    "registryUrl": "<NPM_REGISTRY_URL>",
    "token": "<NEW_TOKEN>"
  }'

Network requirements

For Superblocks Cloud (SaaS) organizations, your registry must be reachable from Superblocks’ infrastructure. The Network requirements section on the Package Registry page lists the source egress IPs Superblocks connects from; your registry must accept TCP/443 from these addresses. Use Copy or Copy all to add them to your registry’s or firewall’s allowlist.

Install policy

Separately from registry configuration, an organization Owner controls whether npm packages may run lifecycle scripts. The setting is organization-wide and applies to every install, whichever registry serves the package. Admins who can manage registries still see the control, but it is read-only for them. Some npm packages run lifecycle scripts during installation. For example, sharp and better-sqlite3 compile native binaries. Disabling the scripts prevents arbitrary code execution at install time, but packages that depend on them fail to build. Toggle Allow install scripts in the Install policy section of the Package Registry page:

Setting	Behavior
Enabled (default)	Packages run their `preinstall`, `install`, and `postinstall` scripts normally
Disabled	Installs run with `--ignore-scripts`, and the synthesized `.npmrc` carries `ignore-scripts=true`, so lifecycle scripts never execute

How installs work

Superblocks synthesizes an .npmrc for every install surface: Clark, the dev server, and the build pod. It carries a top-level registry= line for the default registry, plus one @scope:registry= line per scoped registry. A package resolves the same way whichever surface installs it. Those lines point at the Superblocks npm proxy, not at your registry URL. The install authenticates to the proxy with the machine’s own Superblocks token. The proxy decrypts your stored auth token server-side and forwards the request upstream. Your registry credential never lands in an .npmrc on a pod or a laptop, and your registry sees the connection arrive from the Superblocks egress IPs. Before it installs a package, Clark checks the registry that would serve it. If the package is missing, Clark stops and says an admin may need to mirror it, instead of quietly substituting something else. Clark also never refactors an app away from a core dependency that fails to install. When an install does fail, Clark names one of three causes: the registry returned 404, the registry rejected the auth token, or the registry could not be reached. Troubleshooting covers each one. For cloud-prem customers who own their network infrastructure, pair this configuration with network-level controls (e.g. VPC egress rules, NetworkPolicy) that block traffic to registry.npmjs.org.

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). They resolve through your default registry unless you add a scoped registry for @superblocksteam. If you do, that registry must serve every package below, or the editor will not start.

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`	Routing for apps carried over from earlier templates
`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.

Pull-through cache (Artifactory, Nexus, Verdaccio proxy)
Curated allowlist

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.

Package inventory

Admins can list the distinct npm packages in use across all applications using the Admin MCP tool list_distinct_packages_in_org. This requires the policies:manage permission (included for Admin and Owner roles by default; assignable to other roles).

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:

What npm packages are in use across my Superblocks organization?

Troubleshooting

The registry returned 404 for a package

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.

The registry rejected the auth token

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.

The registry could not be reached

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 deployments, ensure the Superblocks data plane has network connectivity to your registry.

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 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.

Scoped packages resolve from the wrong registry

Package resolution is matched by npm scope. Confirm the package name’s scope exactly matches a configured scoped registry (e.g. @mycompany/utils requires a @mycompany scoped registry). Packages whose scope has no dedicated registry (and all unscoped packages) resolve from the default registry. Scopes are case-insensitive and stored lowercase, so @MyCompany and @mycompany are treated as the same scope.

Can't change a scoped registry's scope

A scope is fixed once a scoped registry is saved. To move a registry to a different scope, delete the existing row and add a new scoped registry with the correct scope.

Native packages fail to build after disabling install scripts

Packages like sharp, better-sqlite3, and node-canvas require lifecycle scripts to compile native binaries. If an Owner disabled Allow install scripts, these packages 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.

Org administration

Governance

Billing

Superblocks on AWS

How registries are matched

Configure the default registry

Add a scoped registry

Scope format

Supported registries

Verify a registry

Manage auth tokens

Rotate tokens with the API

Network requirements

Install policy

How installs work

Core required packages

Platform-critical packages

`@superblocksteam/*` scoped packages

Unscoped platform packages

Full dependency closure

Package inventory

Troubleshooting

​How registries are matched

​Configure the default registry

​Add a scoped registry

​Scope format

​Supported registries

​Verify a registry

​Manage auth tokens

​Rotate tokens with the API

​Network requirements

​Install policy

​How installs work

​Core required packages

​Platform-critical packages

​@superblocksteam/* scoped packages

​Unscoped platform packages

​Full dependency closure

​Package inventory

​Troubleshooting

​Related

How registries are matched

Configure the default registry

Add a scoped registry

Scope format

Supported registries

Verify a registry

Manage auth tokens

Rotate tokens with the API

Network requirements

Install policy

How installs work

Core required packages

Platform-critical packages

`@superblocksteam/*` scoped packages

Unscoped platform packages

Full dependency closure

Package inventory

Troubleshooting

Related