Namespaces

Namespaces are used to distinguish and manage registries from different sources.

What Are Namespaces?

A namespace is the first part of a registry ID, starting with the @ symbol, indicating the registry's source.

@namespace/path/to/registry
   ↑          ↑
Namespace   Registry path

Examples

• @company/ui-kit - @company is the namespace, ui-kit is the path
• @company/runtimes/node - @company is the namespace, runtimes/node is the path
• @team/internal-config - @team is the namespace, internal-config is the path

Why Namespaces?

Namespaces give different registry sources independent resolution and access:

• Source mapping: each namespace has its own URL and auth (e.g. @rack → official, @company → internal).
• Conflict avoidance: registries with the same name but different namespaces coexist (@official/ui-kit and @company/ui-kit).
• Access control: the server enforces tokens and publish permissions per namespace, so teams stay isolated.

Official Registry Shorthand

Official registries can omit the @rack prefix and use forms like runtimes/node, frameworks/vue (CLI automatically resolves to @rack/runtimes/node).

Namespace Format

Namespaces must comply with the following rules (enforced by the CLI when parsing identifiers):

• Start with @
• Only lowercase letters, digits, -, and _ are allowed (uppercase is lowercased before validation)
• The first and last characters must be a lowercase letter or digit
• No spaces or other special characters

Regex: ^@[a-z0-9](?:[a-z0-9-_]*[a-z0-9])?$

Valid namespaces

✓ @rack
✓ @company
✓ @my-org
✓ @internal_team
✓ @org2024

Invalid namespaces

✗ rack           # Missing @
✗ @my org        # Contains space
✗ @-company      # Cannot start with -
✗ @company!      # Contains special character
✗ @_internal     # Cannot start with _
✗ @internal_     # Cannot end with _

rk config set/get/remove only checks the leading @; the full regex above is enforced when rk init / rk add parse identifiers.

Official Registries and Shorthand

Official registries live under @rack, organised by Registry Types (runtimes/, frameworks/, build/, ...). The shorthand form (omitting @rack/) is automatically expanded by the CLI.

rk add @rack/runtimes/node     # Full form
rk add runtimes/node           # Shorthand, equivalent to the line above

Configure Namespace Sources

Default Configuration

Rack uses the official source by default; the configuration file lives at ~/.rackrc.

{
  "registries": {
    "@rack": "https://registry.rackjs.com"
  }
}

All namespaces not explicitly configured fall back to the @rack source.

Add Private Source

Enterprises can configure private namespaces to point to internal registry servers.

rk config set @company --url https://registry.company.com

Configuration after adding:

{
  "registries": {
    "@rack": "https://registry.rackjs.com",
    "@company": "https://registry.company.com"
  }
}

Private Source with Authentication

Add authentication for private sources.

rk config set @company --url https://registry.company.com --token your-token-here

You can also pass custom headers directly via --header "Key: Value".

rk config set @company --url https://registry.company.com \
  --header "X-API-Version: v2"

Configuration result (~/.rackrc)

--token is stored as a separate token field. The CLI expands it into an Authorization: Bearer <token> header only when displaying the entry or sending a request — it is not written back into headers.

{
  "registries": {
    "@rack": "https://registry.rackjs.com",
    "@company": {
      "url": "https://registry.company.com",
      "headers": {
        "X-API-Version": "v2"
      },
      "token": "your-token-here"
    }
  }
}

View Configured Namespaces

rk config list

Example output (token is printed in cleartext as an Authorization Bearer header)

Configuration for @rack:
  URL:      https://registry.rackjs.com
Configuration for @company:
  URL:      https://registry.company.com
  Headers:
    Authorization -> Bearer your-token-here
    X-API-Version -> v2

The current version does not mask tokens or sensitive headers. Protect your ~/.rackrc and terminal output.

Remove Namespace Configuration

# Alias: rm; pass -f to skip confirmation
rk config remove @company

After removal, the namespace falls back to the default @rack source. The default @rack namespace cannot be removed.

Namespace Resolution Rules

When running rk add @namespace/name, Rack searches for configuration in the following order.

1. Exact Match

Prioritize the configuration that exactly matches the namespace.

# Configuration
{
  "@company": "https://registry.company.com"
}

# Command
rk add @company/ui-kit
# → Uses https://registry.company.com

2. Fall Back to Default Source

If the namespace is not configured, fall back to the @rack source.

# Configuration
{
  "@rack": "https://registry.rackjs.com"
}

# Command (shorthand form)
rk add frameworks/vue
# → Shorthand, automatically resolved to @rack
# → Final URL: https://registry.rackjs.com/@rack/frameworks/vue/registry.json

Registry URL Structure

Rack builds URLs from the namespace configuration and the registry path; the namespace segment is preserved in the URL.

Registry ID:  @namespace/path/to/name@version
Config map:   @namespace → {host}
Final URL:    {host}/{@namespace}/{path}/{version}/registry.json

When the registry ID has no version, the URL also drops the version segment; once the CLI receives registry.json, it uses item.version to build the actual download URL for template files.

Official registry example

# Registry ID
runtimes/node

# Source configuration
@rack → https://registry.rackjs.com

# Final URL (the shorthand omits the namespace, but it is restored to @rack)
https://registry.rackjs.com/@rack/runtimes/node/registry.json

Enterprise registry example

# Without version
Registry ID:  @company/ui-kit
Final URL:    https://registry.company.com/@company/ui-kit/registry.json

# With version
Registry ID:  @company/runtimes/node@1.2.3
Final URL:    https://registry.company.com/@company/runtimes/node/1.2.3/registry.json

Troubleshooting

Authentication Failure

Error message

Error: 401 Unauthorized

Solution

Check if the token has expired and update authentication information.

rk config set @company --url https://registry.company.com --token new-token-here

Namespace Conflict

Error message

Warning: Namespace @company is already configured

Solution

Using rk config set will automatically override the existing configuration, or remove it first.

rk config remove @company
rk config set @company --url https://new-registry.company.com