Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Context
✓ import { Context } from 'cordis'
✗ const { Context } = require('cordis')
Cordis v4 is ESM-first; CommonJS require() may lead to issues or require specific build configurations. `Context` is the core class for managing services and lifecycles.
Service
✓ import { Service } from 'cordis'
✗ import Service from 'cordis'
`Service` is a named export, not a default. It's the base class for creating extendable, context-aware services within Cordis.
Plugin
✓ import type { Plugin } from 'cordis'
✗ import { Plugin } from 'cordis'
`Plugin` is primarily a TypeScript type used for defining plugin structures. For runtime use, you'd typically define a function or class that adheres to the `Plugin` interface rather than importing `Plugin` as a value.
This quickstart demonstrates creating a Cordis application, registering a custom service with dependency injection, and utilizing context for configuration. It shows how to define a service, make it available within the context, and instantiate it, including creating a child context with overridden configurations.
import { Context, Service } from 'cordis';
interface MyConfig {
greeting: string;
}
class GreeterService extends Service {
static inject = ['config']; // Declare dependencies
constructor(ctx: Context, public config: MyConfig) {
super(ctx, 'greeter'); // Register service as 'greeter'
this.logger.info(`GreeterService initialized with config: ${this.config.greeting}`);
}
greet(name: string): string {
return `${this.config.greeting}, ${name}!`;
}
}
// Main application context
async function bootstrap() {
const app = new Context();
// Register the configuration for the greeter service
app.provide('config', { greeting: 'Hello from Cordis' });
// Register the GreeterService as a plugin
app.plugin(GreeterService);
// Access the greeter service from the context
const greeter = app.greeter as GreeterService; // Type assertion for convenience
if (greeter) {
console.log(greeter.greet('World'));
} else {
console.error('Greeter service not found!');
}
// Demonstrate a child context with different config
const childCtx = app.createContext();
childCtx.provide('config', { greeting: 'Greetings, developer' });
childCtx.plugin(GreeterService);
const childGreeter = childCtx.greeter as GreeterService;
if (childGreeter) {
console.log(childGreeter.greet('Cordis User'));
}
await app.start();
console.log('Cordis application started successfully.');
await app.stop();
console.log('Cordis application stopped.');
}
bootstrap().catch(console.error);
Debug
Known issues
breakingCordis v4 introduces significant breaking changes compared to v3, particularly in its internal architecture and API surface related to context management, service registration, and plugin definition. While specific details for `rc.3` are still being finalized, expect existing v3 codebases to require substantial updates.fixConsult the official Cordis v4 migration guide once available. Be prepared to refactor service definitions, context interactions, and plugin structures. Pay close attention to changes in `Context` and `Service` class methods.
affects: >=4.0.0-rc.0
gotchaCordis heavily leverages an "everything is a plugin" philosophy and context-based dependency injection. Misunderstanding the lifecycle of plugins or the scope of services within different contexts can lead to unexpected behavior or services not being available where anticipated.fixThoroughly review the documentation on context, services, and plugins. Ensure services are correctly `inject`ed and `provide`d. Use `app.createContext()` for isolated environments or specific configurations.
affects: >=4.0.0-rc.0
gotchaAs a modern TypeScript framework, Cordis v4 is built with ESM (ECMAScript Modules) as the primary module system. Attempting to use `require()` for imports in a CommonJS environment without proper configuration (e.g., `"type": "module"` in `package.json` or transpilation) can lead to module resolution errors.fixEnsure your project is configured for ESM. Use `import` statements exclusively. If in Node.js, set `"type": "module"` in `package.json` or rename files to `.mjs`.
affects: >=4.0.0-rc.0
deprecatedBeing in a release candidate phase, some APIs or behaviors introduced in earlier `4.0.0-rc` versions may be deprecated or altered before the stable `4.0.0` release. Relying heavily on specific `rc` internal APIs could lead to breakage upon upgrading to a stable version.fixPrefer documented public APIs. Monitor Cordis's GitHub repository and changelogs for updates on API stability and upcoming changes before the final v4 release. Delay major production deployments until a stable version is available if API stability is critical.
affects: 4.0.0-rc.0 - 4.0.0-rc.3
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'plugin')
Attempting to call `.plugin()` or other context methods on an uninitialized or incorrectly initialized Cordis instance, often when `new Context()` is not called or its result is not assigned.
fixAlways initialize your Cordis application with `const app = new Context();` and ensure `app` is correctly referenced before calling its methods.
Error: Service 'myService' already exists in current context
Attempting to register a service with the same name multiple times within the same Cordis context. This can happen if a plugin is registered more than once or if two different plugins provide the same service name.
fixEnsure each service has a unique name within a given context. If you need different implementations of the same service, use child contexts or conditional plugin registration. For services that should be singletons, manage their registration carefully.
TS2345: Argument of type 'typeof MyService' is not assignable to parameter of type 'Plugin'.
Your service class or plugin function does not fully conform to the `Plugin` type definition. This often occurs if `static inject` is missing, `constructor` arguments are incorrect, or the service lacks expected properties/methods.
fixReview your service/plugin definition against Cordis's `Plugin` interface and service class examples. Ensure all `static inject` dependencies are correctly declared and the constructor matches the expected `(ctx: Context, ...injectedDeps)` signature.
Audit
Dependencies
@cordisjs/plugin-includeoptionalProvides functionality for including or bundling other modules or configurations within the Cordis application context. Often used for organizing and incorporating sub-applications or external resources.
@cordisjs/plugin-loaderoptionalEnables dynamic loading and management of Cordis plugins and configurations at runtime, supporting a flexible and extensible application architecture.