Core

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.

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" },
      config: { secret: "my-secret" },
    },
  },
});

// 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.

Property	Type	Description
`name`	`string`	Project name
`cacheFolder`	`string`	Optional custom cache directory
`modules`	`Record<string, string \| AntelopeModuleConfig>`	Module definitions (shorthand or full)
`logging`	`AntelopeLogging`	Optional logging configuration
`envOverrides`	`Record<string, string \| string[]>`	Optional environment variable overrides
`environments`	`Record<string, Partial<AntelopeConfig>>`	Optional per-environment config overrides
`test`	`AntelopeTestConfig`	Optional test configuration

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.

Property	Type	Description
`version`	`string`	Optional version constraint
`source`	`ModuleSource*`	Source definition (local, git, package, local-folder)
`config`	`unknown`	Optional runtime configuration
`importOverrides`	`ImportOverride[] \| Record<string, string>`	Optional import path redirections
`disabledExports`	`string[]`	Optional list of exports to disable

`AntelopeLogging`

Logging configuration within the project config.

Property	Type	Description
`enabled`	`boolean`	Enable or disable logging
`moduleTracking`	`object`	Track module-level logging with includes/excludes
`channelFilter`	`Record<string, number \| string>`	Filter log output by channel and level
`formatter`	`Record<string, string>`	Custom formatters per channel
`dateFormat`	`string`	Date format string for log timestamps

`AntelopeTestConfig`

Test configuration for the project.

Property	Type	Description
`folder`	`string`	Optional test folder path
`setup`	`Function`	Optional async setup function returning partial config
`cleanup`	`Function`	Optional async cleanup function

Next steps

Introduction - Return to the overview
Modules - Module lifecycle management

Logging

Runtime