registry-item.json

registry.json is the configuration file for a single registry. registry-item.json is the schema used to validate the contents of registry.json, including dependencies, files, scripts, and other fields.

Example

{
  "$schema": "https://rackjs.com/schema/registry-item.json",
  "name": "react",
  "namespace": "@rack",
  "type": "registry:framework",
  "version": "1.0.0",
  "description": "React + TypeScript framework configuration",
  "tags": ["react", "typescript", "framework"],
  "priority": 2,
  "conflicts": ["frameworks/vue"],
  "registryDependencies": ["runtimes/node"],
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^5.0.0"
  },
  "files": [
    {
      "target": "index.html",
      "type": "registry:entry",
      "path": "./templates/react/index.html"
    },
    {
      "target": ".gitignore",
      "type": "registry:config",
      "content": "node_modules\ndist\n.env.local"
    }
  ],
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "envVars": {
    "VITE_APP_TITLE": "My React App"
  },
  "languages": {
    "js": {
      "files": [
        {
          "target": "src/index.jsx",
          "type": "registry:entry",
          "path": "./templates/react-js/src/index.jsx"
        },
        {
          "target": "src/App.jsx",
          "type": "registry:entry",
          "path": "./templates/react-js/src/App.jsx"
        }
      ]
    },
    "ts": {
      "devDependencies": {
        "typescript": "^5.3.0"
      },
      "files": [
        {
          "target": "src/index.tsx",
          "type": "registry:entry",
          "path": "./templates/react/src/index.tsx"
        },
        {
          "target": "src/App.tsx",
          "type": "registry:entry",
          "path": "./templates/react/src/App.tsx"
        },
        {
          "target": "tsconfig.json",
          "type": "registry:config",
          "content": "{\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"jsx\": \"react-jsx\"\n  }\n}"
        }
      ]
    }
  },
  "defaultLanguage": "ts"
}

Field Descriptions

$schema

• Type: string
• Required: No
• Description: Schema URL for editor validation and autocompletion

{
  "$schema": "https://rackjs.com/schema/registry-item.json"
}

name

• Type: string
• Required: Yes
• Format: kebab-case
• Description: Unique identifier for the registry within its namespace

{
  "name": "react"
}

namespace

• Type: string
• Required: Yes
• Format: @ followed by a kebab-case slug (e.g. @rack, @company)
• Description: Namespace the registry belongs to. Combined with name, it forms the globally unique identifier @namespace/name used in rk add commands and dependency references.

{
  "namespace": "@rack"
}

type

• Type: string
• Required: Yes
• Description: Registry type, determines its role in the tech stack

{
  "type": "registry:framework"
}

Available values:

Type	Description	Recommended Priority
registry:runtime	Runtime	1
registry:framework	Framework	2
registry:build	Build tool	3
registry:feature	Feature module	4
registry:testing	Testing tool	5
registry:quality	Quality tool	6

version

• Type: string
• Required: Yes
• Format: Semantic versioning (semver)
• Description: Registry version number

{
  "version": "1.0.0"
}

description

• Type: string
• Required: No
• Description: Functional description of the registry

{
  "description": "React + TypeScript framework configuration"
}

tags

• Type: string[]
• Required: No
• Description: Tag array for categorization and search

{
  "tags": ["react", "typescript", "framework"]
}

priority

• Type: integer (≥ 0)
• Required: No (only name, namespace, type, version are marked required by the schema; however, the CLI install pipeline relies on this field for sorting and version arbitration, so it is strongly recommended to set it explicitly)
• Recommended Range: 1-6 (any non-negative integer is accepted)
• Description: Priority that determines installation order and version conflict resolution. Lower numbers install first and have higher priority.

{
  "priority": 2
}

conflicts

• Type: string[]
• Required: No
• Description: Conflicting registries that cannot be installed together

{
  "conflicts": ["frameworks/vue"]
}

registryDependencies

• Type: string[]
• Required: No
• Description: Other registries to be automatically installed

{
  "registryDependencies": ["runtimes/node"]
}

dependencies

• Type: Record<string, string>
• Required: No
• Description: Production dependencies

{
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

devDependencies

• Type: Record<string, string>
• Required: No
• Description: Development dependencies

{
  "devDependencies": {
    "@vitejs/plugin-react": "^5.0.0",
    "typescript": "^5.3.0"
  }
}

files

• Type: FileObject[]
• Required: No
• Description: Common file list

{
  "files": [
    {
      "target": "index.html",
      "type": "registry:entry",
      "path": "./templates/react/index.html"
    },
    {
      "target": ".gitignore",
      "type": "registry:config",
      "content": "node_modules\ndist\n.env.local"
    }
  ]
}

FileObject structure

Field	Type	Required	Description
target	string	Yes	Target file path
type	string	Yes	FileObject type
content	string	No	Inline file content, mutually exclusive with path
path	string	No	External file path, mutually exclusive with content
executable	boolean	No	Whether executable permission is needed
mergeStrategy	object	No	Merge strategy configuration

For registry:asset, prefer using path. When path is used, the CLI writes the target file in binary mode and applies overwrite behavior.

mergeStrategy configuration

Field	Type	Required	Description
type	string	Yes	Strategy type: builtin or custom
strategy	string	No	Built-in strategy name (only when type: "builtin"): json, ignore, env, overwrite
script	string	No	Plugin script path (only when type: "custom")

Example:

Using built-in strategy:

{
  "files": [
    {
      "target": "myconfig.json",
      "type": "registry:config",
      "path": "./templates/myconfig.json",
      "mergeStrategy": {
        "type": "builtin",
        "strategy": "json"
      }
    }
  ]
}

Using custom plugin:

{
  "files": [
    {
      "target": "myconfig.json",
      "type": "registry:config",
      "path": "./templates/myconfig.json",
      "mergeStrategy": {
        "type": "custom",
        "script": "./scripts/merge-myconfig.js"
      }
    }
  ]
}

FileObject types

• registry:entry - Entry file
• registry:config - Configuration file
• registry:lib - Library file
• registry:test - Test file
• registry:docs - Documentation file
• registry:script - Script file (recommend setting executable: true)
• registry:asset - Static asset file

Usage recommendations

• Use content for simple configs (e.g. .gitignore, small JSON configs)
• Use path for complex code (e.g. React components, complex config files)

scripts

• Type: Record<string, string>
• Required: No
• Description: npm scripts to add to package.json

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

envVars

• Type: Record<string, string>
• Required: No
• Description: Environment variable configuration

{
  "envVars": {
    "VITE_APP_TITLE": "My React App",
    "NODE_ENV": "development"
  }
}

languages

• Type: object
• Required: No
• Description: Language-specific configuration

{
  "languages": {
    "js": {
      "files": [
        {
          "target": "src/index.jsx",
          "type": "registry:entry",
          "path": "./templates/react/js/src/index.jsx"
        }
      ]
    },
    "ts": {
      "devDependencies": {
        "typescript": "^5.3.0"
      },
      "files": [
        {
          "target": "src/index.tsx",
          "type": "registry:entry",
          "path": "./templates/react/ts/src/index.tsx"
        },
        {
          "target": "tsconfig.json",
          "type": "registry:config",
          "content": "{...}"
        }
      ]
    }
  }
}

Available fields (the schema only allows the three below; any other key is rejected)

• dependencies - language-specific production dependencies
• devDependencies - language-specific development dependencies
• files - language-specific files

Fields like scripts, envVars, registryDependencies must live at the registry's top-level (common) configuration; they cannot be placed inside languages.X.

Design principles

• files field stores common files
• languages.js/ts.files stores language-specific files

defaultLanguage

• Type: string (matches ^[a-z0-9-]+$, typically "js" or "ts")
• Required: No (recommended when languages is present)
• Description: Default language used when none is explicitly specified. The CLI resolves the variant in the order: :language suffix on the command line > language field in rack.json > defaultLanguage > "ts".

{
  "defaultLanguage": "ts"
}