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

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, 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 during the execution flow.

Simple String Entry

Pass a relative path string for single-entry applications:

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

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

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:

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, 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:

// 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
2. Register the essential group and its three plugins
3. Register the ui group and its three plugins
4. Invoke 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 — Public API (load, getLoader) and configuration merging
• packages/loader/src/internal.ts — Core entry resolution, group registration, and plugin lifecycle
• 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 and is exposed through 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 tracks group membership and reloads affected plugins while preserving group state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}