Where to Find Cordis Documentation: Official Guides and API References

Cordis documentation is distributed across the root README, individual package READMEs, TypeScript source files in packages/core/src/, and the external Cordis Primer guide.

The Cordis framework by cordiverse maintains a decentralized documentation structure that spans in-repository markdown files and external references. Whether you are bootstrapping a new application with create-cordis or extending the core functionality through custom services, understanding where to find Cordis documentation is essential for effective development.

Entry Points: The Root README and Package Guides

The primary entry point for Cordis documentation resides in the root README.md, which provides a concise project overview and directs users to the main documentation site.

Root README Overview

Located at [README.md](https://github.com/cordiverse/cordis/blob/main/README.md) (lines 1-11), the root file offers a high-level summary of the framework's purpose and links to comprehensive resources. This file serves as the launchpad for new users exploring the cordiverse/cordis repository.

Package-Level READMEs

Each published package contains its own dedicated README describing specific functionality and import methods:

• @cordisjs/utils: Utility functions and helper methods located at [packages/utils/readme.md](https://github.com/cordiverse/cordis/blob/main/packages/utils/readme.md)
• @cordisjs/plugin-loader: Plugin initialization mechanisms documented at [packages/loader/README.md](https://github.com/cordiverse/cordis/blob/main/packages/loader/README.md), with implementation details in [packages/loader/src/internal.ts](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/internal.ts)
• @cordisjs/plugin-hmr: Hot Module Replacement configuration for development at [packages/hmr/README.md](https://github.com/cordiverse/cordis/blob/main/packages/hmr/README.md)
• create-cordis: Bootstrap scaffolding and project creation guide at [packages/create/README.md](https://github.com/cordiverse/cordis/blob/main/packages/create/README.md)

The Cordis Primer (External Reference Guide)

Beyond the repository, the Cordis Primer serves as the authoritative human-readable guide maintained outside the main codebase. This external resource covers core architectural concepts, API surface details, and best-practice patterns for production applications.

Access the primer at Cordis Primer for structured learning paths and in-depth tutorials.

Source Code as Documentation

Since Cordis is implemented in TypeScript, the source files in packages/core/src/ function as authoritative API documentation. These files define public contracts through TypeScript declarations and JSDoc comments, serving as reference material for IDE autocompletion and type checking.

Core Service Definitions

The Service class and lifecycle methods are defined in [packages/core/src/service.ts](https://github.com/cordiverse/cordis/blob/main/packages/core/src/service.ts). This file establishes the base class that all Cordis services must extend, specifying initialization hooks and disposal patterns.

Registry API

Service registration and retrieval mechanisms are implemented in [packages/core/src/registry.ts](https://github.com/cordiverse/cordis/blob/main/packages/core/src/registry.ts). This module exposes the registry.register() and registry.get() methods for managing service dependencies at runtime.

Reflection Utilities

Advanced type introspection capabilities reside in [packages/core/src/reflect.ts](https://github.com/cordiverse/cordis/blob/main/packages/core/src/reflect.ts), providing metadata management for dependency injection scenarios.

Practical Implementation Examples

The documentation sources provide concrete implementation patterns for common Cordis workflows, as demonstrated in the package READMEs and source code.

Bootstrapping a Cordis Application

To initialize a new application, use the createCordis function exported from [packages/create/src/index.ts](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts):

import { createCordis } from '@cordisjs/create'
import { loader } from '@cordisjs/plugin-loader'

const cordis = await createCordis({
  plugins: [loader()],
})

cordis.service.start()

Registering Custom Services

Extend the framework by implementing the Service base class and registering instances via the registry API:

import { Service } from '@cordisjs/core'

class CounterService extends Service {
  private count = 0
  increment() { this.count += 1 }
  get value() { return this.count }
}

cordis.registry.register('counter', new CounterService())
cordis.registry.get('counter')?.increment()

Enabling Hot Module Replacement

For development workflows, configure the HMR plugin as documented in the package README:

import { hmr } from '@cordisjs/plugin-hmr'

await createCordis({
  plugins: [hmr({ watch: './src/**/*.ts' })],
})

Summary

• Root README: Primary entry point at README.md (lines 1-11) linking to external resources
• Package READMEs: Specific documentation for @cordisjs/utils, @cordisjs/plugin-loader, @cordisjs/plugin-hmr, and create-cordis
• Cordis Primer: External comprehensive guide covering architecture and patterns
• Source Code: TypeScript implementations in packages/core/src/service.ts, registry.ts, and reflect.ts serve as definitive API references
• Bootstrap Function: createCordis in packages/create/src/index.ts provides the standard application entry point

Frequently Asked Questions

Where is the main Cordis documentation website?

The primary human-readable guide is the Cordis Primer, hosted externally at https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer. The repository's README.md points to this resource as the definitive reference for learning concepts and patterns, while the source code provides the API reference.

How do I find API documentation for specific Cordis methods?

API documentation is embedded in the TypeScript source files within packages/core/src/. Files such as service.ts and registry.ts contain type definitions and implementation details that serve as the authoritative reference for method signatures, class structures, and lifecycle hooks.

What documentation is available for Cordis plugins?

Individual plugin documentation resides in package-specific READMEs. The @cordisjs/plugin-loader documentation covers plugin initialization with implementation details in packages/loader/src/internal.ts, while @cordisjs/plugin-hmr details Hot Module Replacement configuration. These files are located in their respective packages/ subdirectories.

Is there a quick-start guide for new Cordis projects?

Yes, the create-cordis package includes a dedicated README at packages/create/README.md that explains project scaffolding. Additionally, the createCordis function in packages/create/src/index.ts demonstrates the standard bootstrap pattern for new applications, as shown in the implementation examples.

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