---
title: Author a provider
description: Define an adapter's capability, connection contract, behavior, and runtime responsibilities.
pagination: false
sidebar:
  icon: code-xml
---

A provider adapter describes how an application connects a capability to an integration.
Use the existing [integration catalog](/docs/modules/integrations) 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:

```ts title="src/provider.ts"
/** 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](https://github.com/rel-kit/relkit/tree/main/integrations/packages/redis/src)
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](/docs/modules/integrations#declare-authoring-entrypoints).
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](/docs/api/provider#all-exported-apis) 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](/docs/modules/integrations/local-docker), or see an adapter
in an application in [Cache product prices](/guides/caching/cache-product-prices).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/provider` API](/docs/api/provider)

- [`apps/docs/examples/public-api/provider.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/provider.ts)