Package registry configuration is currently in beta. Contact support to enable it for 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
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
- Navigate to Organization Settings > Package Registry
- Enter your Registry URL, the full URL of your npm-compatible registry (e.g.
https://artifactory.example.com/api/npm/npm-virtual/) - 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
- 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 |
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:- Clark queries your registry to confirm the package is available
- If the package is found, Clark proceeds with the install
- 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
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 configuresnpm to use your registry for all Clark-triggered installs. Clark also checks package availability against your registry before attempting installs.
For cloud-prem 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.- 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 versions and transitive dependencies may change between Superblocks releases. Use the Superblocks MCP server to query packages currently in use across your organization for the latest inventory.
Package inventory
Admins can view the distinct set of npm packages in use across all applications in the organization using the Superblocks MCP server. Compare the output against the 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
Troubleshooting
Installs fail with 'package not in registry'
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.
Installs fail with 'registry authentication failed'
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.
Installs fail with 'registry unreachable'
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
Editor fails to start after configuring a private 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.
Native packages fail to build after disabling install scripts
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.