# Content Client SDK

> How to use the Uniform Content Client to fetch, search, and filter headless content entries.

Source: https://docs.uniform.app/docs/sdk/content-client

> **Deprecated:**
>
> `ContentClient` is deprecated. It is replaced by `EntryDeliveryClient`, `EntryManagementClient`, and `ContentTypeClient`. See [content API clients](https://docs.uniform.app/docs/sdk/content-api-clients) for the current clients and a migration guide.

The Content Client (`ContentClient` from `@uniformdev/canvas`) provides programmatic access to headless content entries stored in Uniform. Use it for server-side data fetching, search indexing, custom API routes, or any scenario where you need to query content outside of the standard composition rendering pipeline.

> **Note:**
>
> Within the App Router SDK's composition rendering flow, content is resolved automatically. The Content Client is for use cases where you need to access content directly -- such as building sitemaps, search indexes, custom API endpoints, or fetching content that isn't part of a composition.

---

## Installation

The Content Client is part of the `@uniformdev/canvas` package:

```bash
npm install @uniformdev/canvas
```

## Initializing the client

```ts
import { ContentClient } from "@uniformdev/canvas";

const contentClient = new ContentClient({
  apiKey: process.env.UNIFORM_API_KEY,
  apiHost: process.env.UNIFORM_CLI_BASE_URL || "https://uniform.global",
  projectId: process.env.UNIFORM_PROJECT_ID,
});
```

The App Router SDK does not provide a pre-configured Content Client factory; initialize the client directly as shown above. For composition access, the App Router SDK provides a pre-configured [Canvas Client](https://docs.uniform.app/docs/sdk/canvas-client#within-the-app-router-sdk).

---

## Fetching entries

### Get entries by content type

```ts
const response = await contentClient.getEntries({
  type: "blogPost",
});

// response.entries is an array of content entries
for (const entry of response.entries) {
  console.log(entry.entry.name, entry.entry.fields);
}
```

### Pagination

```ts
const response = await contentClient.getEntries({
  type: "blogPost",
  limit: 20,
  offset: 0,
});

console.log(`Total entries: ${response.totalCount}`);
```

---

## Search and filtering

The Content Client supports advanced filtering using a structured query syntax. Filters are passed as key-value pairs where the key includes the field path and operator.

### Filter syntax

```
filters.<field>[<operator>]=<value>
```

- **`field`**: The field to filter by. Use `type` for content type, `fields.<fieldName>` for custom fields, or system properties like `name`, `slug`, `created`, `modified`.
- **`operator`**: The comparison operator.
- **`value`**: The literal value to compare against.

### Example: filter by content type and field value

```ts
const response = await contentClient.getEntries({
  filters: {
    "type[eq]": "brand",
    "fields.brandName[match]": "adidas",
  },
});
```

The filter operators, supported fields, reference-field filtering, and how to combine filters are documented on the [Content API clients](https://docs.uniform.app/docs/sdk/content-api-clients#filtering) page. The same operators apply to `ContentClient.getEntries`.

---

## Selecting fields with data projection

The `select` option fetches a subset of each entry instead of the whole thing. The API prunes fields, field types, and slots before values are resolved, so pruned content skips asset resolution, rich text reference expansion, and data resource fetches -- reducing both payload size and response time.

```ts
const response = await contentClient.getEntries({
  filters: { "type[eq]": "article" },
  select: {
    fields: { only: ["title", "coverImage"] },
  },
});
```

The projection buckets, operators, behavior, and further examples are documented on the [Content API clients](https://docs.uniform.app/docs/sdk/content-api-clients#selecting-fields-with-data-projection) page. The same `select` option is available on [`CanvasClient.getCompositionList`](https://docs.uniform.app/docs/sdk/canvas-client#selecting-fields-with-data-projection) and [`RouteClient.get`](https://docs.uniform.app/docs/sdk/route-client#fetching-a-subset-with-select).

---

## Filtering compositions

The [Canvas Client](https://docs.uniform.app/docs/sdk/canvas-client#filtering-compositions) supports the same filter and projection syntax for compositions, with `parameters` in place of `fields`. On the current clients, this is documented under [filtering compositions](https://docs.uniform.app/docs/sdk/content-api-clients#filtering-compositions).

---

## Building a search index

A common use case for the Content Client is building a search index. Here is a pattern that retrieves all compositions via the project map and the [Route Client](https://docs.uniform.app/docs/sdk/route-client), then extracts text content for indexing:

```ts
import { RouteClient } from "@uniformdev/canvas";
import { ProjectMapClient } from "@uniformdev/project-map";

const projectMapClient = new ProjectMapClient({
  apiKey: process.env.UNIFORM_API_KEY,
  projectId: process.env.UNIFORM_PROJECT_ID,
});

const routeClient = new RouteClient({
  apiKey: process.env.UNIFORM_API_KEY,
  projectId: process.env.UNIFORM_PROJECT_ID,
  edgeApiHost: "https://uniform.global",
});

async function buildSearchIndex() {
  // 1. Get all project map nodes with compositions
  const { nodes } = await projectMapClient.getNodes({
    projectMapId: "your-project-map-id",
  });

  const compositionNodes = (nodes ?? []).filter((node) => node.compositionId);

  // 2. Fetch each composition and extract text
  const indexData = await Promise.all(
    compositionNodes.map(async (node) => {
      const route = await routeClient.get({
        path: node.path,
        projectMapId: "your-project-map-id",
        state: 0, // published state
      });

      if (route.type !== "composition") return null;

      const { composition } = route.compositionApiResponse;
      const title = composition.parameters?.pageTitle?.value as string;

      return {
        path: node.path,
        title,
        compositionId: node.compositionId,
      };
    })
  );

  return indexData.filter(Boolean);
}
```

> **Note:**
>
> For large sites, consider running index rebuilds outside the Next.js build process to avoid build timeout limits. You can trigger rebuilds via a webhook when content is published.

---

## Limitations

- **Nested object search is not supported**: You cannot filter by a parameter of a component within a composition, or by a field of a block within an entry.
- **Faceting** is available for numeric and short text fields, but requires specifying a single content type filter.

## Import reference

| Export | Package | Description |
| --- | --- | --- |
| `ContentClient` | `@uniformdev/canvas` | Client for fetching content entries |
| `CanvasClient` | `@uniformdev/canvas` | Client for [fetching compositions](https://docs.uniform.app/docs/sdk/canvas-client) |
| `RouteClient` | `@uniformdev/canvas` | Client for [route resolution](https://docs.uniform.app/docs/sdk/route-client) |
| `ProjectionSpec` | `@uniformdev/canvas` | Type for the `select` data projection option |