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.
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.
Package inventory
Admins can view the distinct set of npm packages in use across all applications in the organization using the Superblocks MCP server. 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
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.