Author a provider

Define an adapter's capability, connection contract, behavior, and runtime responsibilities.

A provider adapter describes how an application connects a capability to an integration. Use the existing integration catalog when you need Redis, S3, or another supported provider. This page is for authors adding an integration.

Define the connection and behavior

Install @relkit/provider in the integration package. Keep its version aligned with the RELKIT packages you test against. The following descriptor declares a cache connection:

/** Builds a provider's serializable authoring descriptor; acquiring a runtime is a separate integration role. */
import {
  defineConnectionContract,
  defineIntegrationReference,
  defineProviderAdapter,
  defineProviderBehavior,
  defineProviderCapability,
} from "@relkit/provider";

export const cacheAdapter = defineProviderAdapter({
  integration: defineIntegrationReference("example-cache"),
  capability: defineProviderCapability("cache"),
  adapterId: "example-cache.v1",
  connectionContract: defineConnectionContract({ url: { sensitive: true } }),
  connection: { url: "redis://127.0.0.1:6379" },
  behavior: defineProviderBehavior({ keyPrefix: "products" }),
});

defineProviderCapability identifies the capability. defineConnectionContract declares allowed connection fields; fields are required by default. Mark credentials and connection URLs as sensitive. defineProviderBehavior holds serializable settings, and defineProviderAdapter checks the field names and produces an immutable descriptor.

This example produces metadata; it does not connect to Redis. The runtime integration owns connection acquisition, capability operations, cancellation, readiness, and cleanup. Follow the Redis implementation for an existing implementation of these separate responsibilities.

Publish the correct entrypoints

Declare the authoring import in relkit.integration.exports.authoring, as explained in integration registration. Expose runtime and local-recipe entrypoints only for the roles your integration implements. Application configuration imports the authoring descriptor; runtime acquisition remains outside descriptor construction.

The provider API index includes bindings, features, local recipes, connection validation, and their companion types. APIs ending in Effect are the lazy forms for integration authors already composing Effect programs; application configuration can use the synchronous builders shown above.

Continue with local Docker recipes, or see an adapter in an application in Cache product prices.