# How to Use the Cordis API: A Complete Guide to Context and Services

> Learn how to use the Cordis API effectively. Instantiate Context, start it, and access services for streamlined development. A complete guide for developers.

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

---

**To use the Cordis API, instantiate a Context via the `create()` function, initialize it with `await ctx.start()`, and access built-in or custom services directly as properties on the context object.**

The Cordis API provides a modular architecture centered around dependency injection and service-oriented design. In the `cordiverse/cordis` repository, all functionality flows through a central `Context` object that maintains a registry of `Service` classes. Understanding this relationship is essential for leveraging the full capabilities of the Cordis framework.

## Core Architecture of the Cordis API

The Cordis API is built on three foundational components that manage application state and service lifecycle.

### The Context Object

At the heart of the system lies the `Context` class defined in [`packages/core/src/context.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/context.ts). This object serves as an execution sandbox and service registry, storing all available services and providing the attachment points for plugins. Every Cordis application begins with a single root context that propagates to all child services and plugins.

### Service Base Classes

Services in Cordis extend the base `Service` class located in [`packages/core/src/service.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/service.ts). When a service is registered, it becomes accessible as a property on the context using its designated name. For example, the HTTP service attaches as `ctx.http`, the timer service as `ctx.timer`, and the logger as `ctx.logger`. This convention ensures consistent access patterns across the entire API surface.

### Application Creation

The entry point for any Cordis application is the `create()` function exported from [`packages/create/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts). This factory function constructs a new `Context` instance, registers all core services (logging, loader, HMR, timer), and returns an application object ready for startup. For CLI-based workflows, [`packages/create/src/bin.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/bin.ts) provides a command-line wrapper around this same initialization logic.

## Implementing the Cordis API in Three Steps

Accessing and utilizing the Cordis API follows a deterministic pattern: create, start, and invoke.

### Step 1: Instantiate the Application

Import the `create` function from `@cordis/create` and invoke it with optional configuration parameters. This returns a `Context` instance that represents your application.

```typescript
import { create } from '@cordis/create'

const app = create({
  // Optional configuration passed to core services
})

const ctx = app // The app itself is the Context

```

### Step 2: Initialize Services

Before accessing any APIs, you must start the context. The `await ctx.start()` method (also available as `app.start()`) initializes all registered services and loads configured plugins. This step is mandatory as it triggers the dependency injection container and sets up the service registry.

```typescript
await app.start()

```

### Step 3: Access Service Methods

Once started, every service becomes available as a property on the context object. Invoke methods directly using the `ctx.<serviceName>.<method>()` pattern.

```typescript
// HTTP client request
const response = await ctx.http.get('https://api.example.com/data')

// Schedule delayed execution
ctx.timer.setTimeout(() => console.log('Task complete'), 2000)

// Structured logging
ctx.logger.info('Application initialized successfully')

```

## Working with Built-in Services

The Cordis API ships with several core services that provide essential infrastructure functionality.

### HTTP Client Service

The `ctx.http` service handles outbound network requests. It supports standard HTTP methods and integrates with the context lifecycle for automatic cleanup.

```typescript
const data = await ctx.http.get('https://api.example.com/users')

```

### Timer and Scheduling

The `ctx.timer` service provides `setTimeout` and `setInterval` implementations that are scoped to the context lifecycle. When the context stops, pending timers automatically clean up to prevent memory leaks.

```typescript
ctx.timer.setInterval(() => {
  ctx.logger.debug('Periodic health check')
}, 5000)

```

### Structured Logging

Access the logger via `ctx.logger` to emit categorized log messages. The logging service supports multiple levels (debug, info, warn, error) and integrates with the loader system for plugin-specific log scoping.

```typescript
ctx.logger.info('Server listening on port 3000')

```

## Extending the Cordis API with Custom Plugins

You can extend the Cordis API by creating custom plugins that inject new methods into the context. The `definePlugin` utility from `@cordis/create` provides type-safe plugin registration.

```typescript
import { definePlugin } from '@cordis/create'

const helloPlugin = definePlugin('hello', ctx => ({
  greet(name: string) {
    ctx.logger.info(`Greeting generated for ${name}`)
    return `Hello, ${name}!`
  },
}))

// Register the plugin
app.plugin(helloPlugin)

// Use the new API
console.log(ctx.greet('World')) // Output: Hello, World!

```

The [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts) module handles the dynamic injection of these plugin-provided symbols. Once loaded, new methods appear on the context automatically without requiring additional imports in consuming code.

## Summary

- **Create** a Cordis application using the `create()` function from [`packages/create/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts) to obtain a root `Context` instance.
- **Start** the application with `await ctx.start()` to initialize the service registry and load plugins, as defined in [`packages/core/src/context.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/context.ts).
- **Access** all functionality through the context object, where services like `ctx.http`, `ctx.timer`, and `ctx.logger` become available as properties.
- **Extend** the API by creating custom plugins with `definePlugin()` that inject new methods directly onto the context.
- **Understand** that [`packages/core/src/service.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/service.ts) defines how all services attach to the context, while [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts) manages runtime plugin loading and hot-module replacement.

## Frequently Asked Questions

### How do I create a Cordis application instance?

Import the `create` function from `@cordis/create` and call it to instantiate a new `Context`. This function, located in [`packages/create/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/create/src/index.ts), constructs the execution sandbox and registers all core services including logging, loading, and HMR capabilities.

### What is the difference between a Context and a Service in Cordis?

The `Context` (defined in [`packages/core/src/context.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/context.ts)) is the central registry and execution environment, while `Service` classes (from [`packages/core/src/service.ts`](https://github.com/cordiverse/cordis/blob/main/packages/core/src/service.ts)) are the functional units attached to that context. Services are accessible as properties on the context instance, such as `ctx.http` or `ctx.logger`, following the naming convention defined in their service implementation.

### Do I need to call `start()` before using Cordis services?

Yes, you must await `ctx.start()` before accessing any service methods. This invocation triggers the initialization sequence in [`packages/loader/src/index.ts`](https://github.com/cordiverse/cordis/blob/main/packages/loader/src/index.ts), which loads plugins, resolves dependencies, and activates all registered services. Attempting to use services before starting the context will result in undefined behavior or missing methods.

### How can I add custom functionality to the Cordis API?

Use the `definePlugin()` utility to create a plugin that returns an object with your custom methods. When registered via `app.plugin()`, the loader injects these methods onto the context object, making them available as `ctx.yourMethodName()`. This mechanism allows seamless extension of the Cordis API without modifying core source files.