Concepts

Configuration

Configure your Antelopejs project with antelope.config.ts — define modules, sources, environment overrides, logging, and per-environment settings.

Configuration File

Antelopejs uses antelope.config.ts as its configuration file. The framework expects a TypeScript config file at the root of your project, providing full type safety and autocompletion through the defineConfig helper.

antelope.config.ts

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    // Module definitions
  }
});

The defineConfig helper provides full type checking for your configuration. Place the configuration file in the root of your project directory.

Dynamic Configuration

The config file can export a function instead of a static object. The function receives a context object with the current environment, allowing you to vary settings based on deployment target.

antelope.config.ts

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig((ctx) => ({
  name: "my-project",
  modules: {
    "my-module": {
      source: { type: "local", path: "./modules/my-module" },
      config: {
        apiUrl: ctx.env === "production" ? "https://api.prod.com" : "http://localhost:3000"
      }
    }
  }
}));

Full Configuration Reference

The top-level configuration object accepts the following fields. All fields except name are optional.

interface AntelopeConfig {
  name: string;                                            // Project name
  cacheFolder?: string;                                    // Default: ".antelope/cache"
  modules?: Record<string, string | AntelopeModuleConfig>; // Module definitions
  logging?: AntelopeLogging;                               // Logging configuration
  envOverrides?: Record<string, string | string[]>;        // Environment variable mappings
  environments?: Record<string, Partial<AntelopeConfig>>;  // Per-environment overrides
  test?: AntelopeTestConfig;                               // Test configuration
}

Module Definitions

Define modules as a simple version string (shorthand for an npm package) or as a full configuration object with source, config, and overrides.

antelope.config.ts

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    // Shorthand: npm package with version
    "my-module": "1.0.0",

    // Full configuration
    "my-other-module": {
      source: { type: "local", path: "./modules/my-module" },
      config: { port: 3000 },
      importOverrides: { "@antelopejs/interface-db": "postgres-module" },
      disabledExports: ["@antelopejs/interface-legacy"]
    }
  }
});

The shorthand format "my-module": "1.0.0" is equivalent to specifying a package source with that version. Use the full object form when you need local sources, custom config, import overrides, or disabled exports.

Module Source Types

Each module source type tells the core where to find the module code and how to load it. The following table summarizes the available types.

Type	Description
`local`	Local filesystem path to a TypeScript/JavaScript project.
`local-folder`	Local folder loaded directly without compilation.
`package`	npm package fetched from a registry.
`git`	Git repository cloned and built.

Local Source

Point to a module on your local filesystem. The core watches the specified directories for changes during development.

{
  type: "local",
  path: "./modules/my-module",      // Relative path to the module
  main: "custom-entry.js",          // Custom entry point (optional)
  watchDir: ["src", "lib"],         // Directories to watch (optional, string or string[])
  installCommand: "npm run build"   // Command to run after install (optional, string or string[])
}

Package Source

Fetch a module from an npm registry. The core downloads and caches the package automatically.

{
  type: "package",
  package: "@scope/my-module",
  version: "1.0.0"
}

Git Source

Clone a module from a Git repository. You can pin to a specific branch or commit.

{
  type: "git",
  remote: "https://github.com/user/repo.git",
  branch: "main",                                        // optional
  commit: "abc123",                                      // optional
  installCommand: "npm install && npm run build"          // optional
}

Local Folder Source

Load a module directly from a folder without any compilation step. This source type is useful for pre-built modules or JavaScript-only projects.

{
  type: "local-folder",
  path: "./modules/my-module",
  watchDir: "src",                  // optional
  installCommand: "npm install"     // optional
}

Import Overrides

Import overrides route interface imports to specific modules. When a module imports an interface, the core checks the override map to determine which provider module should fulfill the request.

antelope.config.ts

{
  importOverrides: {
    "@antelopejs/interface-database": "postgres-module"
  }
}

Override mapping is useful when multiple modules implement the same interface and you need to control which implementation a specific consumer receives.

Disabled Exports

Prevent a module from providing specific interfaces. The module still loads and runs, but the core does not register the listed interfaces from it.

antelope.config.ts

{
  disabledExports: ["@antelopejs/interface-legacy"]
}

Environment Variable Overrides

The envOverrides field maps environment variables to configuration paths. When an environment variable is set, its value overrides the corresponding configuration value at runtime. The path uses dot notation to target nested fields.

antelope.config.ts

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    "db-module": {
      config: { host: "localhost", port: 5432 }
    }
  },
  envOverrides: {
    "DB_HOST": "modules.db-module.config.host",
    "DB_PORT": "modules.db-module.config.port"
  }
});

With this configuration, setting DB_HOST=db.prod.com in your environment overrides the host value in the db-module config. Environment variable overrides keep sensitive or deployment-specific values out of your configuration file.

Template Substitution

Use ${path} syntax in string configuration values to reference other values within the same config block. The core resolves these references before passing the config to the module.

antelope.config.ts

{
  config: {
    host: "localhost",
    port: 5432,
    url: "${host}:${port}/mydb"  // Resolves to "localhost:5432/mydb"
  }
}

Environment-Specific Configuration

The environments field defines per-environment overrides. Each key is an environment name, and its value is a partial configuration that merges on top of the base config when that environment is active.

antelope.config.ts

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  name: "my-project",
  modules: {
    "api-module": {
      config: { port: 3000 }
    }
  },
  environments: {
    production: {
      modules: {
        "api-module": {
          config: { port: 8080 }
        }
      }
    }
  }
});

Run your project with a specific environment using the -e flag. The flag accepts any environment name defined in your configuration.

ajs project dev -e production

The base configuration applies first, then the environment-specific overrides merge on top. The environment block overrides only the fields you specify — everything else keeps its base value.

Logging Configuration

Configure log output directly in the config file. The logging section controls which channels appear, their minimum severity level, and the output format.

antelope.config.ts

{
  logging: {
    enabled: true,
    moduleTracking: {
      enabled: true,
      includes: ["my-module"],    // Only show logs from these modules
      excludes: ["noisy-module"]  // Hide logs from these modules
    },
    channelFilter: {
      "default": "info",          // Level name or number
      "http": 10                  // DEBUG level
    },
    formatter: {
      "default": "{{chalk.gray(DATE)}} {{chalk.blue(LEVEL_NAME)}} {{ARGS}}"
    },
    dateFormat: "yyyy-MM-dd HH:mm:ss"
  }
}

See the Logging page for a full explanation of severity levels, channels, and filtering options.

Complete configuration example

The following example combines all configuration features into a single realistic file. Each field includes an inline comment explaining its role.

antelope.config.ts

import { defineConfig } from "@antelopejs/interface-core/config";

export default defineConfig({
  // Project name — identifies this project in logs and CLI output
  name: "my-fullstack-app",

  // Directory for build artifacts and cached modules (default: ".antelope/cache")
  cacheFolder: ".antelope/cache",

  modules: {
    // Shorthand: npm package source — version string resolves to { type: "package", version }
    "@antelopejs/module-auth": "2.1.0",

    // Local source: point to a module on disk, with a watch directory for live reload
    "api-module": {
      source: {
        type: "local",
        path: "./modules/api",
        watchDir: ["src"],
        installCommand: "npm install"
      },
      config: {
        port: 3000,
        host: "localhost",
        url: "${host}:${port}"         // template substitution — resolves to "localhost:3000"
      },
      importOverrides: {
        "@antelopejs/interface-database": "postgres-module"
      },
      disabledExports: ["@antelopejs/interface-legacy-api"]
    },

    // Git source: clone a module from a remote repository
    "analytics-module": {
      source: {
        type: "git",
        remote: "https://github.com/your-org/analytics-module.git",
        branch: "main",
        installCommand: "npm install && npm run build"
      },
      config: {
        trackingId: "UA-000000-1"
      }
    },

    // Package source (explicit form): fetch from an npm registry
    "postgres-module": {
      source: {
        type: "package",
        package: "@antelopejs/module-postgres",
        version: "1.3.0"
      },
      config: {
        host: "localhost",
        port: 5432,
        database: "app_dev"
      }
    }
  },

  // Map environment variables to configuration paths using dot notation
  envOverrides: {
    "DB_HOST": "modules.postgres-module.config.host",
    "DB_PORT": "modules.postgres-module.config.port",
    "DB_NAME": "modules.postgres-module.config.database",
    // A single env var can override multiple paths
    "API_HOST": [
      "modules.api-module.config.host",
      "modules.analytics-module.config.endpoint"
    ]
  },

  // Per-environment overrides — merged on top of the base config
  environments: {
    production: {
      modules: {
        "api-module": {
          config: { port: 8080, host: "0.0.0.0" }
        },
        "postgres-module": {
          config: { host: "db.prod.internal", database: "app_prod" }
        }
      },
      logging: {
        enabled: true,
        channelFilter: { "default": "warn" }
      }
    },
    staging: {
      modules: {
        "postgres-module": {
          config: { host: "db.staging.internal", database: "app_staging" }
        }
      }
    }
  },

  // Logging configuration — controls console output for all modules
  logging: {
    enabled: true,
    moduleTracking: {
      enabled: true,
      includes: ["api-module", "postgres-module"],
      excludes: []
    },
    channelFilter: {
      "default": "info",
      "http": 10
    },
    formatter: {
      "default": "{{chalk.gray(DATE)}} {{chalk.blue(LEVEL_NAME)}} {{ARGS}}"
    },
    dateFormat: "yyyy-MM-dd HH:mm:ss"
  }
});

Key takeaways

Shorthand modules accept a version string and resolve to the package source type automatically.
envOverrides keep secrets and deployment-specific values out of the config file. Set DB_HOST in your shell or CI environment and the value flows into the correct module config.
environments let you maintain a single config file for development, staging, and production. Only the fields you specify in an environment block are overridden.
Template substitution (${host}:${port}) references other values in the same config block, so you can build derived strings without duplication.