# 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

```ts
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.

```ts
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" },
    },
  },
});
```

```ts
// 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:

```ts
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:

```ts
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:

```ts
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:

```ts
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](./1.introduction.md) - Return to the overview
- [Modules](./5.modules.md) - Module lifecycle management