Directus SDK

Use the Directus SDK in TypeScript projects. It provides concise request helpers and mostly type-safe access to a Directus instance.

Configure a client

To get started with the Directus SDK, install the required dependency:

pnpm add @directus/sdk

npm install @directus/sdk

yarn add @directus/sdk

bun add @directus/sdk

Then configure your client:

import { createDirectus, rest, staticToken } from "@directus/sdk";
import type { Schema } from "@my-generated-schema";
const DIRECTUS_BASE_URL = "https://content.onderwijsloket.com";
const DIRECTUS_TOKEN = "<my-api-token>";

const directus = createDirectus<Schema>(DIRECTUS_BASE_URL)
  .with(staticToken(DIRECTUS_TOKEN))
  .with(rest());

To create a type-aware client, you must pass a Schema type argument. There is currently no official type package available for the Onderwijsloket API, but you can generate type definitions based on the OpenAPI specification. Refer to the related guide for instructions.

Send requests with SDK commands

The SDK exposes various commands that can be used with the client. In most cases, you will primarily use readItem and readItems. A full list of available commands can be found in the SDK source code.

/**
 * Check the Directus SDK source code for all available commands
 * @link https://github.com/directus/directus/tree/main/sdk/src/rest/commands
 */
import { readItems } from '@directus/sdk'

/**
 * articles will be typed as:
 * Pick<Schema['articles'], 'id' | 'title' | 'slug'>[]
 */
const articles = await directus.request(
    readItems('articles', {
        filter: {
            status: {
                _eq: 'published'
    },
        }
        fields: ['id', 'title', 'slug'],
        limit: 5
    })
)

Know the type-inference limits

While the SDK provides type safety, it can also introduce some limitations.

Do not infer non-null fields from filters

Filter rules are not reflected in inferred types. For example, if you apply a { _nnull: true } filter to a field, that field may still be typed as null.

Check types for relational fields

A larger issue occurs with relational fields not being properly resolved in the inferred types. This may require you to cast the type manually or use type guards.

/**
 * Article type is inferred as:
 * {
 *   id: string
 *   authors: string[] | { authors_id: string | null | { name: string } }[]
 * }
 *
 * Even though we requested embedded fields, the SDK still resolves
 * the type as a potential string.
 */
const article = await directus.request(
  readItem("articles", "<article-id>", {
    fields: [
      "id",
      {
        authors: [
          {
            authors_id: ["name"]
          }
        ]
      }
    ]
  })
);