Module Development

Interface Registry

What Is the Interface Registry

The interface registry is a git repository that acts as a catalog of available interfaces and their implementations. The AntelopeJS CLI queries this registry to help developers discover and install modules.

Registering an interface is optional. Modules and interfaces work without being listed in the registry. The registry provides two CLI conveniences:

ajs project modules install — The CLI scans your project for unresolved interface dependencies and suggests implementations from the registry
ajs module init — The CLI can propose registered interfaces when scaffolding a new module

The registry does not host code. The registry only stores metadata (descriptions and source locations). The actual interface packages and implementation modules live on npm, git, or local paths.

Registry Structure

The registry is a git repository with one directory per interface. Each directory contains a manifest.json file that describes the interface and lists available implementations.

interfaces/
├── auth/
│   └── manifest.json
├── database/
│   └── manifest.json
└── api/
    └── manifest.json

Antelopejs maintains an official registry. Organizations can also host private registries for internal interfaces.

Manifest Format

Each manifest.json describes the interface and lists the modules that implement it.

manifest.json

{
  "description": "User management interface",
  "modules": [
    {
      "name": "user-module-mongodb",
      "source": {
        "type": "package",
        "package": "@antelopejs/user-mongodb",
        "version": "1.0.0"
      }
    }
  ]
}

Field	Description
`description`	Short summary of what the interface provides
`modules`	List of modules that implement this interface
`modules[].name`	Display name of the implementing module
`modules[].source`	Source definition (package, git, or local)

The modules array can contain multiple implementations. When a developer runs ajs project modules install, the CLI presents all listed modules and lets them choose the implementation that fits their needs.

Adding to the Registry

Registering an interface or adding a new implementation follows a contribution workflow through the registry repository.

Create or update the manifest

Write a manifest.json for your interface if the registry does not have one yet. If the interface already has a manifest, add your module to the modules array.

manifest.json

{
  "description": "Payment processing interface",
  "modules": [
    {
      "name": "payment-stripe",
      "source": {
        "type": "package",
        "package": "@your-org/payment-stripe",
        "version": "1.0.0"
      }
    }
  ]
}

Make your module available

Publish the implementing module to npm or make it accessible through a git repository. The registry points to your module's source — developers download the module directly from there.

Submit a pull request

Open a pull request against the registry repository with your manifest changes. The repository maintainers review the manifest before merging.

Custom Registry

Organizations can host a private registry for internal interfaces that should not appear in the official catalog.

ajs config set git https://github.com/your-org/your-interfaces.git

The CLI uses your custom repository for interface discovery. The repository must follow the same directory structure — one directory per interface, each containing a manifest.json.

Private registries work with any git hosting service. Use SSH URLs or access tokens for repositories that require authentication.

CLI Integration

The registry powers the ajs project modules install command. The CLI automates interface discovery and module installation for projects with unresolved dependencies.

ajs project modules install

The installation process follows these steps:

The CLI scans your modules for interface imports that have no corresponding implementation
The CLI fetches the registry and looks up each unresolved interface
Available implementations are presented for selection
The selected module is added to your project's antelope.config.ts

After installation, the new module is downloaded and ready to use the next time you start the project. The interface imports in your existing modules automatically resolve to the newly installed implementation.

Testing

Test Antelopejs modules with the built-in test runner — configure the test environment, write isolated tests, and validate interface implementations.

API Routing

Build HTTP APIs with controllers, route decorators, parameter extraction, and structured responses in AntelopeJS.