# How to Configure Entry and Group Settings in Cordis Loader: A Complete Guide

> Master Cordis loader entry and group settings. Learn to define application entry points and organize plugins for efficient management in this comprehensive guide.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: how-to-guide
- Published: 2026-08-23

---

The **Cordis loader** accepts a configuration object where you define your application's entry point (via the `entry` field) and organize plugins into logical collections (via the `group` array) that can be started and stopped together.

The **Cordis loader** is the entry point for any Cordis-based application. Located in [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts), it merges your configuration with internal defaults, resolves module paths dynamically, and registers plugin groups for lifecycle management. Understanding how to configure entry and group settings in Cordis loader is essential for structuring scalable applications with fine-grained control over plugin orchestration.

---

## Entry Configuration in Cordis Loader

The **entry** field tells the loader which module to load as your application's starting point. This configuration is processed in [`packages/loader/src/internal.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/internal.ts) during the execution flow.

### Simple String Entry

Pass a relative path string for single-entry applications:

```ts
// cordis.config.ts
import { load } from '@cordiverse/loader';

await load({
  entry: './src/main.ts'
});

```

The path resolves **relative to the project root**. If the exported module contains a `setup` function, the loader invokes it automatically with the Cordis context.

### Named Entry Map

Use an object for multi-entry projects:

```ts
await load({
  entry: {
    api: './src/api.ts',
    worker: './src/worker.ts',
    scheduler: './src/scheduler.ts'
  }
});

```

Each key becomes a named entry that the loader can reference independently. This pattern supports microservice architectures where different processes share configuration but run distinct code paths.

---

## Group Configuration in Cordis Loader

The **group** field is an array of group descriptors that enable bulk plugin lifecycle operations. Groups are registered through the loader's internal helper before the entry's `setup` function executes.

### Basic Group Structure

```ts
await load({
  entry: './src/main.ts',
  group: [
    {
      name: 'core',
      plugins: ['@cordiverse/plugin-logger', '@cordiverse/plugin-config']
    },
    {
      name: 'features',
      plugins: ['@cordiverse/plugin-chat', '@cordiverse/plugin-notifications']
    }
  ]
});

```

Each descriptor requires:
- `name`: Logical identifier for the group
- `plugins`: Array of plugin identifiers (package names as strings)

### Group Lifecycle Control

Groups enable programmatic batch operations:

```ts
import { load, getLoader } from '@cordiverse/loader';

await load({
  entry: './src/main.ts',
  group: [
    { name: 'backend', plugins: ['@cordiverse/db', '@cordiverse/auth'] },
    { name: 'frontend', plugins: ['@cordiverse/ui', '@cordiverse/router'] }
  ]
});

const loader = getLoader();
await loader.startGroup('backend');   // Starts DB and auth plugins
await loader.stopGroup('frontend');   // Stops UI and router plugins

```

This mechanism, implemented in [`packages/loader/src/internal.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/internal.ts), defers plugin activation until explicitly triggered—useful for staged initialization or feature toggling.

---

## Complete Configuration Example

This production-ready setup demonstrates combined entry and group configuration in Cordis loader:

```ts
// loader-config.ts
import { load } from '@cordiverse/loader';

await load({
  // Entry point: main application module
  entry: './src/app.ts',

  // Logical plugin organization
  group: [
    {
      name: 'essential',
      plugins: [
        '@cordiverse/plugin-logger',
        '@cordiverse/plugin-config',
        '@cordiverse/plugin-errors'
      ]
    },
    {
      name: 'ui',
      plugins: [
        '@cordiverse/plugin-theme',
        '@cordiverse/plugin-navigation',
        '@cordiverse/plugin-notifications'
      ]
    }
  ],

  // Optional: enable hot-module replacement
  hmr: true
});

```

**Execution sequence:**
1. Resolve and dynamically import [`./src/app.ts`](https://github.com/cordiverse/cordis/blob/main/./src/app.ts)
2. Register the **essential** group and its three plugins
3. Register the **ui** group and its three plugins
4. Invoke [`app.ts`](https://github.com/cordiverse/cordis/blob/main/app.ts)'s exported `setup` with the populated Cordis context

---

## Key Implementation Files

Understanding these source locations helps debug configuration issues:

- **[`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts)** — Public API (`load`, `getLoader`) and configuration merging
- **[`packages/loader/src/internal.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/internal.ts)** — Core entry resolution, group registration, and plugin lifecycle
- **[`packages/group/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/group/src/index.ts)** — Helper utilities for group management

---

## Summary

- **Entry configuration** accepts either a string path or a named object map; paths resolve relative to project root
- **Group configuration** uses descriptors with `name` and `plugins` arrays to collect related plugins
- Groups enable **bulk lifecycle operations** via `startGroup()` and `stopGroup()` methods
- The loader automatically calls the entry module's `setup` function, passing the context with all registered plugins
- All configuration processing occurs in [`packages/loader/src/internal.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/internal.ts) and is exposed through [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts)

---

## Frequently Asked Questions

### What happens if I omit the group field in my Cordis loader configuration?

The loader operates normally with no groups registered. Plugins must then be loaded individually through the entry module's `setup` function rather than through group-based lifecycle methods.

### Can I use multiple entry points simultaneously in Cordis?

Yes. Provide a named entry object, but note that the loader processes entries sequentially. For true parallel execution, spawn separate loader instances with distinct configurations.

### How does Cordis resolve plugin identifiers in the group array?

Plugin identifiers are **package names**—the same strings passed to `loadPlugin()`. The loader verifies these against installed packages during group registration, throwing if a plugin cannot be found.

### Is hot-module replacement (HMR) compatible with group configurations?

Yes. Set `hmr: true` in your loader configuration. When enabled, the watcher in [`packages/loader/src/internal.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/internal.ts) tracks group membership and reloads affected plugins while preserving group state.