{"id":10672,"library":"cordis","title":"Cordis Meta-Framework","description":"Cordis is an actively developed meta-framework for building modern applications, emphasizing a concept of \"Spatiotemporal Composability\" and a highly modular, plugin-based architecture. Currently in release candidate phase (v4.0.0-rc.3), it aims to provide a structured and opinionated layer on top of underlying JavaScript runtime environments, facilitating the development of complex systems by handling common concerns like service orchestration, lifecycle management, and resource allocation. Its \"everything is a plugin\" philosophy promotes high cohesion, low coupling, and extensive extensibility, allowing developers to customize and extend core functionalities through well-defined plugin interfaces. The framework is written in TypeScript, providing strong type safety across its API. While an exact release cadence isn't specified, its `cordiverse` organization shows continuous, active development across its ecosystem. It differentiates itself by offering a robust context and service management system designed for flexible application composition, particularly useful in environments requiring dynamic loading and unloading of modules or services.","status":"active","version":"4.0.0-rc.3","language":"javascript","source_language":"en","source_url":"https://github.com/cordiverse/cordis","tags":["javascript","typescript"],"install":[{"cmd":"npm install cordis","lang":"bash","label":"npm"},{"cmd":"yarn add cordis","lang":"bash","label":"yarn"},{"cmd":"pnpm add cordis","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides 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.","package":"@cordisjs/plugin-include","optional":true},{"reason":"Enables dynamic loading and management of Cordis plugins and configurations at runtime, supporting a flexible and extensible application architecture.","package":"@cordisjs/plugin-loader","optional":true}],"imports":[{"note":"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.","wrong":"const { Context } = require('cordis')","symbol":"Context","correct":"import { Context } from 'cordis'"},{"note":"`Service` is a named export, not a default. It's the base class for creating extendable, context-aware services within Cordis.","wrong":"import Service from 'cordis'","symbol":"Service","correct":"import { Service } from 'cordis'"},{"note":"`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.","wrong":"import { Plugin } from 'cordis'","symbol":"Plugin","correct":"import type { Plugin } from 'cordis'"}],"quickstart":{"code":"import { Context, Service } from 'cordis';\n\ninterface MyConfig {\n  greeting: string;\n}\n\nclass GreeterService extends Service {\n  static inject = ['config']; // Declare dependencies\n\n  constructor(ctx: Context, public config: MyConfig) {\n    super(ctx, 'greeter'); // Register service as 'greeter'\n    this.logger.info(`GreeterService initialized with config: ${this.config.greeting}`);\n  }\n\n  greet(name: string): string {\n    return `${this.config.greeting}, ${name}!`;\n  }\n}\n\n// Main application context\nasync function bootstrap() {\n  const app = new Context();\n\n  // Register the configuration for the greeter service\n  app.provide('config', { greeting: 'Hello from Cordis' });\n\n  // Register the GreeterService as a plugin\n  app.plugin(GreeterService);\n\n  // Access the greeter service from the context\n  const greeter = app.greeter as GreeterService; // Type assertion for convenience\n  if (greeter) {\n    console.log(greeter.greet('World'));\n  } else {\n    console.error('Greeter service not found!');\n  }\n\n  // Demonstrate a child context with different config\n  const childCtx = app.createContext();\n  childCtx.provide('config', { greeting: 'Greetings, developer' });\n  childCtx.plugin(GreeterService);\n  const childGreeter = childCtx.greeter as GreeterService;\n  if (childGreeter) {\n    console.log(childGreeter.greet('Cordis User'));\n  }\n\n  await app.start();\n  console.log('Cordis application started successfully.');\n  await app.stop();\n  console.log('Cordis application stopped.');\n}\n\nbootstrap().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult 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.","message":"Cordis 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.","severity":"breaking","affected_versions":">=4.0.0-rc.0"},{"fix":"Thoroughly 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.","message":"Cordis 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.","severity":"gotcha","affected_versions":">=4.0.0-rc.0"},{"fix":"Ensure 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`.","message":"As 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.","severity":"gotcha","affected_versions":">=4.0.0-rc.0"},{"fix":"Prefer 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.","message":"Being 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.","severity":"deprecated","affected_versions":"4.0.0-rc.0 - 4.0.0-rc.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Always initialize your Cordis application with `const app = new Context();` and ensure `app` is correctly referenced before calling its methods.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'plugin')"},{"fix":"Ensure 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.","cause":"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.","error":"Error: Service 'myService' already exists in current context"},{"fix":"Review 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.","cause":"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.","error":"TS2345: Argument of type 'typeof MyService' is not assignable to parameter of type 'Plugin'."}],"ecosystem":"npm"}