Antelope
Get Started

Project

Your Antelopejs project brings together modules that work as a team. Each module has its own job and settings.

Create a project

Getting started with Antelopejs is super easy. The CLI wizard walks you through creating a new project step by step.

Most projects have your own application module plus other modules that provide services your app needs.

Run this command:

npx @antelopejs/core project init <project-name>

Answer a few questions to set up your project file

The CLI will create an antelope.json file based on your answers.

Add your code module

You can either add your existing code or create a new module from a template.

Manage your project

Everything in your project revolves around the antelope.json file. This file tells Antelopejs:

  • What modules to load and where to find them
  • How to configure each module
  • Different settings for different environments

The CLI gives you simple commands to add, remove, and update modules. Check out the CLI documentation for details on all the commands.

Project Configuration with antelope.json

The antelope.json file is where you define how your project is assembled from modules. Unlike traditional applications with complex folder structures, an Antelopejs project is extremely minimal - at its core, it only requires an antelope.json file.

A minimal Antelopejs project could be as simple as:

my-antelope-project/
└── antelope.json          # Project configuration

antelope.json

This is the heart of your project. It defines which modules to load and how they should be configured:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My Antelopejs project",
  "author": "Your Name",
  "cacheFolder": ".antelope/cache",
  "modules": {
    "app": {
      "source": {
        "type": "local",
        "path": "."
      },
      "config": {
        "port": 3000
      }
    },
    "database": {
      "source": "mongodb-module@1.0.0",
      "config": {
        "url": "mongodb://localhost:27017"
      }
    }
  },
  "logging": {
    "enabled": true,
    "dateFormat": "yyyy-MM-dd HH:mm:ss",
    "moduleTracking": {
      "enabled": true,
      "includes": ["app", "database"],
      "excludes": []
    },
    "formatter": {
      "40": "{{chalk.gray}}[{{DATE}}] {{chalk.red}}{{chalk.bold}}[ERROR]{{chalk.reset}} {{ARGS}}",
      "default": "{{chalk.gray}}[{{DATE}}] {{LEVEL_NAME}} {{ARGS}}"
    }
  },
  "environments": {
    "development": {
      "cacheFolder": ".antelope/cache_dev",
      "modules": {
        "database": {
          "config": {
            "url": "mongodb://localhost:27017"
          }
        }
      }
    },
    "production": {
      "cacheFolder": ".antelope/cache_prod",
      "modules": {
        "database": {
          "config": {
            "url": "mongodb://prod-server:27017"
          }
        }
      }
    }
  },
  "envOverrides": {
    "DATABASE_URL": "modules.database.config.url",
    "API_PORT": "modules.api.config.port"
  }
}

The main sections include:

  1. Basic Info: Name, version, description, author
  2. Cache Folder: Configuration for module caching
  3. Modules: Definition of each module and how it should be configured
  4. Logging: Configuration for the logging system
  5. Environments: Environment-specific configurations

Cache Folder Configuration

The cacheFolder setting specifies where Antelopejs will store downloaded modules and their dependencies:

"cacheFolder": ".antelope/cache"

This folder is used to:

  • Store downloaded NPM packages
  • Cache Git repositories
  • Store module versions and dependencies
  • Improve loading times by reusing previously downloaded modules

By default, if not specified, Antelopejs will use ".antelope/cache" in your project root.

Module Definition

You can add modules to your project in several ways:

Get a module from NPM:

"api": {
  "source": "api-module@1.2.0",
  "config": {
    "port": 3000
  }
}

For a complete guide to all available options, see the Module Definition section in the Module Management chapter.

Interface Overrides

You can configure multiple modules to implement the same interface with unique identifiers:

"mongodb": {
  "source": {
    "type": "package",
    "name": "@antelopejs/mongodb",
    "version": "0.0.1"
  },
  "config": {
    "url": "mongodb://localhost:27017"
  },
  "importOverrides": [
    {
      "interface": "database@beta",
      "source": "mongodb",
      "id": "main"
    }
  ]
},
"mongodb-2": {
  "source": {
    "type": "package",
    "name": "@antelopejs/mongodb",
    "version": "0.0.1"
  },
  "config": {
    "url": "mongodb://localhost:27018"
  },
  "importOverrides": [
    {
      "interface": "database@beta",
      "source": "mongodb-2",
      "id": "secondary"
    }
  ]
}

The importOverrides field allows you to register multiple implementations of the same interface, each with its own configuration and unique identifier. This enables you to route interface imports to the appropriate module implementation.

In the example above, we include the MongoDB module twice, each exporting the same database@beta interface but configured differently to connect to different database instances. With importOverrides, we assign different IDs (main and secondary) to these interface connections and route each ID to the appropriate module source. This allows us to later use the specific interface connection we need at runtime.

For details on how to discover and use these interface instances at runtime, see the Interface Discovery section.

Disabling Specific Exports

Sometimes a module may export interfaces that you don't need in your project:

"redis": {
  "source": {
    "type": "package",
    "name": "@antelopejs/redis",
    "version": "0.0.1"
  },
  "config": {
    "url": "redis://localhost:6379"
  },
  "disabledExports": ["redis_scheduler@beta"]
}

In this example:

  • The module exports both redis@beta and redis_scheduler@beta interfaces
  • You only need to use redis@beta
  • By adding redis_scheduler@beta to the disabledExports array, imports to @ajs/redis_scheduler/beta will not be forwarded to this module

Environment Configuration

You can use environment variables to change settings dynamically:

"envOverrides": {
  "DATABASE_URL": "modules.database.config.url",
  "API_PORT": "modules.api.config.port"
}

This maps environment variables to specific paths in your configuration. When the environment variable is set, its value replaces the content at the specified path. For example, if you set DATABASE_URL=mongodb://production-db:27017 in your environment, it will override modules.database.config.url with that value at runtime.

Logging Configuration

You can customize the logging behavior of your project directly in the antelope.json file:

Enable or disable logging and set basic options:

"logging": {
  "enabled": true,
  "dateFormat": "yyyy-MM-dd HH:mm:ss",
  "formatter": {
    "default": "{{chalk.gray}}[{{DATE}}] {{LEVEL_NAME}} {{ARGS}}"
  }
}

This configuration enables logging with a standard date format and a simple default message format.

You can manage logging through the CLI with these commands:

# View current logging configuration
ajs project logging show

# Set logging options
ajs project logging set --enable true
ajs project logging set --module-tracking true
ajs project logging set --format-level error "{{chalk.red}}[ERROR] {{ARGS}}"

For complete details on logging CLI commands, see the CLI documentation.

Architecture

Let's dig into how Antelopejs is built - you'll see how its design helps you create modular apps that are easy to update and extend.

Module

Modules are the building blocks of your Antelopejs app. They talk to each other through interfaces - exporting features others can use, and importing features they need.