# What Are the Main Components of Cordis? Core Architecture Explained

> Discover the core components of Cordis, including Core, Loader, Include, and HMR. Learn how its monorepo architecture enables runtime plugin management and hot-module replacement.

- Repository: [Cordiverse/cordis](https://github.com/cordiverse/cordis)
- Tags: architecture
- Published: 2026-09-13

---

**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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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.

```typescript
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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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.

```typescript
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`](https://github.com/cordiverse/cordis/blob/main/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.

```typescript
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`](https://github.com/cordiverse/cordis/blob/main/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.

```typescript
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`](https://github.com/cordiverse/cordis/blob/main/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.

```typescript
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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts) and [`packages/create/src/bin.ts`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/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`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/bin.ts) to generate a new project structure with proper configuration files and dependency management.