What Are the Main Components of Cordis? Core Architecture Explained

Cordis is organized as a monorepo of nine focused packages—Core, Loader, Include, HMR, Group, Create, Timer, Logger-Console, and Utils—that together provide a meta-framework for runtime plugin management, fiber-based task scheduling, and hot-module replacement capabilities.

Cordis employs a modular architecture designed for building extensible applications through dynamic plugin systems. The framework divides functionality across distinct workspaces declared in the top-level package.json, allowing independent versioning while maintaining tight integration. Understanding the main components of Cordis reveals how the framework achieves its plugin-centric design and runtime isolation.

The Core Runtime (@cordisjs/core)

The Core package serves as the foundation of the framework, exporting the primary API from packages/core/src/index.ts. This component provides the Context class for dependency injection, the EventBus for inter-service communication, and the Fiber system for concurrent task management.

The Core implements Service registration patterns that allow plugins to expose functionality to other parts of the application. It also includes a built-in Logger interface that defines structured logging contracts used throughout the ecosystem.

import { createApp } from '@cordisjs/create';
import consoleLogger from '@cordisjs/plugin-logger-console';

const app = createApp();
app.plugin(consoleLogger());

In this example, createApp() instantiates the Core runtime, while the plugin system demonstrates how the Core accepts extensions without direct coupling to specific implementations.

Plugin Management and Isolation

Cordis separates plugin lifecycle concerns into three dedicated packages that handle loading, runtime inclusion, and logical grouping.

Dynamic Loading with the Loader (@cordisjs/loader)

The Loader package, defined in packages/loader/src/index.ts, handles plugin discovery and isolation. It exports functions like resolve for mapping plugin identifiers to modules, isolate for creating sandboxed execution contexts, and group for managing plugin collections.

This component reads configuration files and prepares plugins for instantiation without immediately executing them, enabling deferred loading strategies.

Runtime Inclusion (@cordisjs/include)

While Loader prepares plugins statically, the Include package (packages/include/src/index.ts) enables hot inclusion at runtime through the app.include() method. This allows applications to load new functionality after initialization, handling journal persistence and state management for dynamically added plugins.

import include from '@cordisjs/plugin-include';

app.plugin(include());
await app.include('my-awesome-plugin');

Plugin Grouping (@cordisjs/group)

The Group package (packages/group/src/index.ts) provides the group helper function that bundles multiple plugins into a single logical unit. This composition pattern simplifies configuration management and allows treating related plugins as atomic entities during lifecycle operations.

import group from '@cordisjs/plugin-group';

app.plugin(group([
  consoleLogger(),
  // other plugins…
]));

Development and Operational Tools

Beyond the core runtime, Cordis provides specialized packages for development workflows and operational concerns.

Hot Module Replacement (@cordisjs/hmr)

The HMR package (packages/hmr/src/index.ts) implements hot-module-replacement for plugins, allowing code updates without application restart. This development tool monitors file changes and orchestrates safe plugin teardown and reinstantiation, preserving application state across updates.

import hmr from '@cordisjs/plugin-hmr';

app.plugin(hmr());

Task Scheduling (@cordisjs/timer)

Built on top of the Core's fiber system, the Timer package (packages/timer/src/index.ts) provides timing utilities including sleep, setInterval, and clearInterval. These functions integrate with the framework's cooperative multitasking model, ensuring scheduled tasks respect the fiber execution boundaries.

import { sleep } from '@cordisjs/timer';

await sleep(1000); // pause for 1 second
app.logger.info('One second elapsed');

Console Logging (@cordisjs/logger-console)

The Logger-Console package (packages/logger-console/src/index.ts) provides the concrete implementation of the Core's Logger interface. It formats structured log output for terminal consumption, serving as the default logging backend during development.

Project Scaffolding (@cordisjs/create)

The Create package (packages/create/src/index.ts and packages/create/src/bin.ts) delivers both programmatic and CLI interfaces for bootstrapping new Cordis projects. It handles template resolution, dependency installation, and initial configuration generation, exporting createApp as the primary entry point for application instantiation.

Shared Utilities (@cordisjs/utils)

The Utils package (packages/utils/src/index.ts) contains cross-cutting helper functions used throughout the framework, including deep-merge utilities and type guards. These tools ensure consistent behavior across package boundaries while avoiding duplication of common logic.

Summary

• Core provides the runtime context, service registry, and fiber-based execution environment through packages/core/src/index.ts.
• Loader, Include, and Group manage plugin lifecycles through resolution, runtime loading, and logical composition.
• HMR enables live plugin updates during development without process restarts.
• Timer offers fiber-aware scheduling utilities for asynchronous operations.
• Create and Logger-Console provide developer ergonomics through scaffolding tools and structured logging.
• Utils supplies shared helper functions that maintain consistency across the monorepo.

Frequently Asked Questions

What distinguishes the Loader from the Include component?

The Loader handles static plugin resolution and isolation during application startup, while Include enables dynamic plugin loading at runtime through app.include(). Loader focuses on preparation and sandboxing defined in packages/loader/src/index.ts, whereas Include manages journal persistence for plugins added after initialization.

How does Hot Module Replacement work in Cordis?

The HMR package monitors plugin files for changes and coordinates safe teardown and reinstantiation cycles via packages/hmr/src/index.ts. It leverages the Core's service registry to preserve application state while swapping plugin implementations, allowing development changes to reflect immediately without restarting the process.

What is the fiber-based execution model in Cordis Core?

The Fiber system in packages/core/src/index.ts implements cooperative multitasking for plugin operations, ensuring that long-running tasks yield control back to the runtime. This architecture prevents plugin code from blocking the main thread while maintaining deterministic execution order across concurrent operations.

How do I scaffold a new Cordis project?

Use the Create package by importing createApp from @cordisjs/create for programmatic instantiation, or run the CLI from packages/create/src/bin.ts to generate a new project structure with proper configuration files and dependency management.

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