Configuration

Overview

The @antelopejs/interface-core/config module exports TypeScript types and the defineConfig helper for defining AntelopeJS project configurations. These types describe module sources, logging settings, environment overrides, and test configurations.

Start with one local module

Put this in antelope.config.ts, replacing the source path with your module's directory. The module itself must already exist; defineConfig does not generate it.

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

export default defineConfig({
  name: "my-project",
  modules: {
    app: {
      source: { type: "local", path: "./modules/app" },
    },
  },
});

defineConfig returns its input unchanged. It supplies TypeScript checking, not runtime validation or module loading. Use the source and field reference below as you add modules; config variables and provider overrides are optional advanced features.

Import

import { defineConfig } from "@antelopejs/interface-core/config";
import type {
  AntelopeConfig,
  AntelopeModuleConfig,
  AntelopeLogging,
  ModuleSource,
  ModuleSourceLocal,
  ModuleSourceGit,
  ModuleSourcePackage,
  ModuleSourceLocalFolder,
} from "@antelopejs/interface-core/config";

defineConfig

The defineConfig function provides type-safe configuration definition. It accepts either a static configuration object or a function that receives a context and returns a configuration.

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

// Static configuration
export default defineConfig({
  name: "my-project",
  modules: {
    database: "@antelopejs/database",
    auth: {
      version: "1.0.0",
      source: {
        type: "package",
        package: "@antelopejs/auth",
        version: "1.0.0",
      },
      // Supply provider-specific configuration through your deployment's secret handling.
    },
  },
});

// Dynamic configuration based on environment
export default defineConfig((ctx) => {
  return {
    name: "my-project",
    modules: {
      database: {
        source: {
          type: "package",
          package: "@antelopejs/database",
          version: "1.0.0",
        },
        config: {
          host: ctx.env === "production" ? "db.prod.internal" : "localhost",
        },
      },
    },
  };
});

AntelopeConfig

The root configuration object for an AntelopeJS project.

Module sources

Each module source type specifies how to locate and load the module code.

Local source

Load a module from a local file path:

const config: AntelopeModuleConfig = {
  source: {
    type: "local",
    path: "./modules/my-module",
    main: "index.ts",
    watchDir: "src",
    installCommand: "pnpm install",
    reloadCommand: "pnpm build",
  },
};

The optional reloadCommand runs instead of installCommand on hot reload, letting you configure a faster command chain (for example, skipping pnpm install).

Git source

Load a module from a Git repository:

const config: AntelopeModuleConfig = {
  source: {
    type: "git",
    remote: "https://github.com/org/module.git",
    branch: "main",
    installCommand: "pnpm install",
  },
};

Package source

Load a module from an npm package:

const config: AntelopeModuleConfig = {
  source: {
    type: "package",
    package: "@antelopejs/database",
    version: "1.0.0",
  },
};

Local folder source

Load a module from a local folder with optional file watching:

const config: AntelopeModuleConfig = {
  source: {
    type: "local-folder",
    path: "./packages/shared",
    watchDir: ["src", "lib"],
    installCommand: ["pnpm install", "pnpm build"],
    reloadCommand: "pnpm build",
  },
};

Like the local source, local-folder also accepts an optional reloadCommand that runs in place of installCommand on hot reload.

AntelopeModuleConfig

Full module configuration within the project config.

An ImportOverride is { interface, source?, id? }. The first entry for an interface pins it to the source module; further entries are connections reached through GetInterfaceInstance(interface, id). An entry for a standalone interface may omit source, declaring a connection to that self-hosted interface.

This project-file contract also applies to SaveModuleDeclaration. It differs intentionally from the runtime ModuleDefinition.importOverrides: Record<string, string[]> accepted by LoadModule; the two types are not interchangeable. Use the type of the API you are calling rather than changing or casting the override shape.

AntelopeLogging

Logging configuration interpreted by the core runtime. All fields are optional. These settings configure the runtime's output; they do not change the raw events sent to a custom logging listener.

Config variables

A module can publish named values other modules reference from their own configuration. The provider declares the names it publishes in its package.json, returns them from its provide callback, and the core substitutes them into every consumer before any module constructs.

{
  "name": "api",
  "antelopeJs": {
    "configVars": ["API_PORT"]
  }
}

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

export async function provide(config: unknown): Promise<ConfigVars> {
  const port = await reservePort(config);
  return { API_PORT: port };
}

provide is optional and only providers implement it. It runs before every construct, so a provider cannot await another module's interface from it: nothing has constructed yet. The core interfaces registered before the module lifecycle starts — GetRuntimeInfo() among them — stay available, which is enough to compute a port, a base URL or a generated secret.

A consumer references the value with ${@<moduleName>.<VAR_NAME>}, where <moduleName> is the module key used in the project configuration:

export default defineConfig({
  name: "my-project",
  modules: {
    api: { version: "1.0.0" },
    dms: {
      version: "1.0.0",
      config: { apiBaseUrl: "http://127.0.0.1:${@api.API_PORT}" },
    },
  },
});

Values are resolved once, before construction, and never re-resolved afterwards. construct cannot publish config variables: its return value is ignored. See the core documentation for the resolution order and the failure modes.

AntelopeTestConfig

Test configuration for the project.

Next steps

• Introduction - Return to the overview
• Modules - Module lifecycle management