TypeScript SDK

The Contismo TypeScript SDK is the official TypeScript client for the Contismo GraphQL Content API. Use it to query content, run mutations, introspect your schema, and generate TypeScript types for your project.

The package is published on npm as @contismo/sdk.

Install

Install the SDK in your application:

pnpm add @contismo/sdk

The SDK requires Node.js 20 or newer.

Authentication

The SDK authenticates with a Contismo GraphQL API key and sends the required project and environment headers automatically.

API keys are created in the Studio under Settings → API Keys.

| Key prefix | Access | | ---------- | ------ | | gql_ | Queries and introspection | | gqlw_ | Queries, mutations, and introspection |

Use a gql_ key for read-only delivery clients. Use a gqlw_ key only where your application needs to create, update, or delete content.

Configuration

Most projects should add a contismo.config.ts file at the project root:

import { defineConfig } from "@contismo/sdk/config";

export default defineConfig({
  client: {
    apiKey: "gql_...",
    endpoint: "https://graphql.contismo.com",
    project: "your-project-id",
    environment: "production",
  },
});

The required client options are:

| Option | Description | | ------ | ----------- | | apiKey | GraphQL API key from the Studio | | endpoint | GraphQL endpoint, usually https://graphql.contismo.com | | project | Project ID, sent as X-Project-Id | | environment | Environment API ID, sent as X-Environment |

Quick Start

With contismo.config.ts in place, create a client without arguments:

import { ContismoClient } from "@contismo/sdk";

const client = new ContismoClient();

const posts = await client.fetch("BlogPost", {
  select: {
    _id: true,
    title: true,
  },
  limit: 10,
});

The first argument to fetch is the content model API ID from the Studio.

Explicit Client Setup

If your app does not use a config file, pass credentials directly:

import { ContismoClient } from "@contismo/sdk";

const client = new ContismoClient({
  apiKey: "gql_...",
  endpoint: "https://graphql.contismo.com",
  project: "your-project-id",
  environment: "production",
});

If your config file lives somewhere else, pass its path:

const client = new ContismoClient({
  config: "./config/contismo.config.ts",
});

Generate TypeScript Types

The SDK includes a contismo CLI that can pull your live GraphQL schema and generate TypeScript types.

Add contismo.config.ts to your project.
Add optional codegen settings if you want to change the output paths.
Run pnpm contismo generate.

import { defineConfig } from "@contismo/sdk/config";

export default defineConfig({
  client: {
    apiKey: "gql_...",
    endpoint: "https://graphql.contismo.com",
    project: "your-project-id",
    environment: "production",
  },
  codegen: {
    outputDir: "./src/generated",
    outputFile: "contismo.ts",
    schemaDir: "./contismo",
  },
});

pnpm contismo generate

By default, generation writes:

contismo/schema.json
src/generated/contismo.ts
contismo-models.ts

After generating types, use them with fetch and fetchOne:

import { ContismoClient } from "@contismo/sdk";
import type { Entry_BlogPost } from "./generated/contismo";

const client = new ContismoClient();

const posts = await client.fetch<Entry_BlogPost>("BlogPost", {
  select: {
    _id: true,
    title: true,
  },
  limit: 10,
});

Introspection

Use introspect to read the GraphQL schema programmatically:

const schema = await client.introspect();

The SDK also exports writeIntrospectionResult if you want to write the result to disk in a custom workflow.

Query Content

Use fetch to query a list of entries with a Prisma-style select object:

const posts = await client.fetch("BlogPost", {
  select: {
    _id: true,
    title: true,
    author: {
      name: true,
    },
  },
  limit: 10,
});

Use fetchOne when you know the entry ID:

const post = await client.fetchOne("BlogPost", {
  id: "entry-id-here",
  select: {
    _id: true,
    title: true,
  },
});

Nested objects in select become nested GraphQL selections. Use true for scalar fields.

Raw GraphQL

Use query when you want to provide the GraphQL document yourself:

const data = await client.query(
  `
  query BlogPost($id: ID!) {
    blogPost(id: $id) {
      _id
      title
    }
  }
`,
  { id: "entry-id-here" },
);

This is useful when you want full control over the operation or when copying a query from the GraphQL Explorer.

Mutations

Mutations require a read/write API key with the gqlw_ prefix. The SDK blocks client.mutate() calls before making a network request when the client is configured with a read-only gql_ key.

const client = new ContismoClient({
  apiKey: "gqlw_...",
  endpoint: "https://graphql.contismo.com",
  project: "your-project-id",
  environment: "production",
});

await client.mutate(
  `
  mutation CreatePost($input: BlogPostCreateInput!) {
    createBlogPost(input: $input) {
      _id
      _status
      title
    }
  }
`,
  {
    input: {
      title: "Hello world",
    },
  },
);

For mutation shapes and generated operation names, see the GraphQL API reference.

Error Handling

SDK errors can be detected with isContismoError:

import {
  ContismoClient,
  ContismoGraphQLError,
  isContismoError,
} from "@contismo/sdk";

const client = new ContismoClient();

try {
  await client.query(`query { blogPost(id: "missing") { _id } }`);
} catch (error) {
  if (isContismoError(error) && error instanceof ContismoGraphQLError) {
    console.error(error.code, error.message);
  }
}